Skip to main content

Lightweight framework for building REST API using AWS Lambda + API Gateway

Project description


CI/CD Status Coverage Status Latest Version PyPI - Downloads License

pylambdarest is a lightweight opinionated framework for building REST API using AWS Lambda and API Gateway.


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.


  • 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.
  • Optional body schema and query parameters validation.


Install the package from PyPI using pip:

$ pip install pylambdarest

pylambdarest should also be included in the deployment package of your Lambda functions.

Getting started

pylambdarest 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 pylambdarest import 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 pylambdarest import route

def handler(request, event, context):
    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 pylambdarest import route

def get_user(user_id):

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

    return 200, user

Schema Validation

pylambdarest optionally provides schema validation using jsonschema:

from pylambdarest import route

user_schema = {
    "type": "object",
    "properties": {
        "name": {"type": "string"}
    "required": ["name"],
    "additionalProperties": False

def create_user(request):
    # If the request's body does not
    # satisfy the user_schema,
    # a 400 will be returned

    # Create user here

    return 201

query_params_schema = {
    "type": "object",
    "properties": {
        # Only string types are allowed for query parameters.
        # Types casting should be done in the handler.
        "page": {"type": "string"}
    "additionalProperties": False

def get_users(request):
    page = int(request.query_params.get("page", 1))

    # request users in db
    users = [
        {"userId": i}
        for i in range((page - 1) * 50, page * 50)

    return 200, users


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.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pylambdarest-0.2.1.tar.gz (6.5 kB view hashes)

Uploaded source

Built Distribution

pylambdarest-0.2.1-py3-none-any.whl (6.8 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page