restful-aws-lambda

restful-aws-lambda is a lightweight opinionated framework for building REST API using AWS Lambda and API Gateway.

Motivation

Why another framework ?

When using API Gateway and python Lambda functions, the most common pattern is to have a unique Lambda function triggered by a proxy API Gateway resource. The Lambda then uses a framework like Flask to do all the routing. In an API Gateway + Lambda context, I feel like the routing should be handled by API Gateway itself, then forwarding the request to specific Lambda functions for each resource or endpoint.

Features

• No routing. Yes, this is a feature. Routing should be handled by API Gateway.
• API Gateway event parsing (including request body and path parameters).
• Cleaner syntax.
• Customizable JSON dumps behavior
• No schema validation

Installation

Install the package from PyPI using pip:

$ pip install restful-aws-lambda

restful-aws-lambda should also be included in the deployment package of your Lambda functions.

Getting started

restful-aws-lambda provides a @route decorator to parse the API Gateway event into a Request object available in the handler function as an argument. It also formats the handler's output to the expected Lambda + API Gateway format seamlessly.

Turning this:

import json

def handler(event, context):
    body = json.loads(event["body"])
    query_params = event["queryStringParameters"]
    path_params = event["pathParameters"]

    return {
        "statusCode": 200,
        "body": json.dumps({
            "message": f"Hello from AWS Lambda {body['name']}!!"
        })
    }

Into this:

from restful_aws_lambda import route


@route
def handler(request):
    body = request.json
    query_params = request.query_params
    path_params = request.path_params

    return 200, {"message": f"Hello from AWS Lambda {body['name']}!!"}

You can still access the original event and context arguments from the handler:

from restful_aws_lambda import route


@route
def handler(request, event, context):
    print(event)
    body = request.json

    return 200, {"message": f"Hello from AWS Lambda {body['name']}!!"}

Path parameters defined in API Gateway can also be accessed directly as function argument:

from restful_aws_lambda import route


@route
def get_user(user_id):
    print(user_id)

    # get user from db
    user = {"id": user_id, "name": "John Doe"}

    return 200, user

JSON dumps options

restful-aws-lambda uses the default json library to dump the lambda handler response. You can customize the behavior of it by passing json.dumps() keyword arguments to the json= parameter:

import json
import datetime
from restful_aws_lambda import route

class JSONDatetimeEncoder(json.JSONEncoder):
    def default(self, obj):
        if isinstance(obj, (datetime.date, datetime.datetime)):
            return obj.isoformat()

        return super(JSONDatetimeEncoder, self).default(obj)


@route(json={"cls": JSONDatetimeEncoder})
def lambda_handler(request):
    today = datetime.date.today()
    return 200, {"today": today}

Example

You can look at the sample for a minimal pylambdarest API.

In this sample, we use the serverless framework to declare the API Gateway -> Lambda routing

The packaging of the Lambda functions is done using the serverless-python-requirements plugin.