Quickstart
- Write a handler function that takes a
request
object and returns a response - Click "Deploy" to make your function live
Endpoint URL
- Your API is now live at this URLFunction 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
ormultipart/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.
- For
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 theContent-Type
header. - For
application/json
content, the JSON is parsed into an object. - For form data (
application/x-www-form-urlencoded
ormultipart/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)}"
}