Quickstart

1. Write a handler function that takes a request object and returns a response
2. Click "Deploy" to make your function live
3. Endpoint URL - Your API is now live at this URL
4. Function URL - Use this URL to view and edit your function

Handler Method

The handler method is the entry point for your serverless function. It receives an HTTP request and returns an HTTP response. The function signature is:

def handler(request):
  return response

To add additional methods, you need to define them outside of the handler function, and then call them from within the handler function. Here's an example:

Request Object

When your function is invoked, it receives a request object containing detailed information about the incoming HTTP request. This object is structured as follows:

Properties

• method (string): The HTTP method used for the request (e.g., GET, POST, PUT, DELETE).
• path (string): The full URL path that triggered the function.
• params (object): An object containing query parameters included in the URL.
• headers (object): An object containing HTTP headers included with the request.
• body (string | object): The body of the request. Its type depends on the Content-Type header:
  • For application/json, it will be a parsed JSON object.
  • For application/x-www-form-urlencoded or multipart/form-data, it will be an object representing the form fields.
  • For other content types, it will be a string containing the raw body content.

Example

Here's an example of what a request object might look like:

{
  "method": "POST",
  "path": "/api/v1/users",
  "params": {
    "include_details": "true"
  },
  "headers": {
    "Content-Type": "application/json",
    "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36"
  },
  "body": {
    "username": "johndoe",
    "email": "johndoe@example.com"
  }
}

Notes

• The body content is automatically parsed based on the Content-Type header.
• For application/json content, the JSON is parsed into an object.
• For form data (application/x-www-form-urlencoded or multipart/form-data), the form fields are parsed into an object.
• For other content types, the body is provided as a raw string.
• File uploads are not supported and will result in an error response.
• The maximum allowed request body size is 100 KB (102,400 bytes).

Response Handling

When your function processes the request and is ready to return a response, the response is structured based on what your function returns:

• Returning Nothing: If your function doesn't return anything or returns null, a response with a status code of 204 (No Content) will be generated, indicating that the request was successful but there is no content to return.

• Returning a String: If your function returns a simple string, this string will be treated as the body of the response with a status code of 200 (OK). The content type will be set to text/plain by default.

• Returning an Object or Array: If your function returns an object or array, it will be serialized into JSON and returned with a status code of 200 (OK). The content type will be set to application/json.

• Custom Responses: If you need to customize the response further (e.g., setting a specific status code, headers, or content type), you can return a dictionary with the following keys:

  • statusCode: The HTTP status code (e.g., 200 for OK, 404 for Not Found).
  • headers: A dictionary of headers to include in the response.
  • body: The content of the response, which can be a string or JSON-serializable data.

Example Usage

Here’s how you might structure your function to return different types of responses:

• Simple String Response:

  def handler(request):
      return "Hello, World!"

• JSON Response:

  def handler(request):
      return {"message": "Hello, World!"}

• Custom Response:

  def handler(request):
      return {
          "statusCode": 404,
          "headers": {"Content-Type": "text/plain"},
          "body": "Resource not found"
      }

Logging

Logs are automatically captured for each function invocation, logs will appear at the bottom of the function page. You can use the print function to log messages to the console.

def handler(request):
    print("This is a log message")
    return "Hello, World!"

Example

This function takes a query parameter from the request, makes an external API call using the requests package, parses the response, and returns a custom error message if something goes wrong. Otherwise, it returns a success message.

import os
import requests
 
def handler(request):
    param_value = request.get('params', {}).get('param_name')
    if not param_value:
        return {
            "statusCode": 400,
            "body": "Missing 'param_name' in query parameters."
        }
 
    api_key = os.getenv('API_KEY')
    api_url = f"https://api.example.com/data?query={param_value}&apiKey={api_key}"
 
    return make_external_request(api_url)
 
def make_external_request(api_url):
    try:
        response = requests.get(api_url)
        response.raise_for_status()
        return {
            "statusCode": 200,
            "body": response.json()
        }
    except requests.exceptions.RequestException as e:
        return {
            "statusCode": 500,
            "body": f"External API request failed: {str(e)}"
        }
    except ValueError as e:
        return {
            "statusCode": 500,
            "body": f"JSON decoding failed: {str(e)}"
        }