wellapi 0.11.1

A simple web framework for aws lambda

WellAPI

WellAPI is a lightweight web framework for building APIs on AWS Lambda and API Gateway.

Documentation

• Practical usage guide: docs/framework-usage.md

Features

• Lambda-first route definitions (GET, POST, PUT, PATCH, DELETE)
• Type-based request parsing and validation with Pydantic
• Dependency injection via Depends
• Middleware and custom exception handlers
• OpenAPI generation compatible with API Gateway integrations
• SQS handlers and scheduled job handlers
• Packaging helpers for Lambda app code and dependency layers

Installation

Install the base package:

pip install wellapi

Install with optional extras:

pip install "wellapi[local,deploy,telemetry]"

• local: local server/test tooling
• deploy: AWS CDK integration
• telemetry: native OpenTelemetry support (traces, metrics, logs) — see docs/telemetry.md

Quick Start

main.py:

from wellapi import WellApi

app = WellApi(title="My API", version="1.0.0")

@app.get("/hello")
def hello():
    return {"message": "Hello, World!"}

Create a handlers/ directory for additional endpoints if needed:

handlers/
  __init__.py
  users.py

Local Development

Run with Uvicorn:

uvicorn main:app --reload

If your handlers are not in the default handlers/ directory, configure it in pyproject.toml:

[wellapi]
handlers_dir = "your_handlers_dir"

CLI

Generate OpenAPI:

wellapi openapi main:app handlers --output openapi.json

Enable CORS in OpenAPI output:

wellapi openapi main:app handlers --output openapi.json --cors true --role_name WellApiRole

Build deployment artifacts:

wellapi build app app.zip
wellapi build dep deps.zip

Deploy with AWS CDK

from aws_cdk import Stack
from constructs import Construct
from wellapi.build.cdk import WellApiCDK


class MyStack(Stack):
    def __init__(self, scope: Construct, id_: str, **kwargs) -> None:
        super().__init__(scope, id_, **kwargs)

        WellApiCDK(
            self,
            "WellApiCDK",
            app_srt="main:app",
            handlers_dir="handlers",
            cors=True,
            cache_enable=False,
            log_enable=True,
        )

Notes

• API Gateway cache support applies to GET endpoints.
• For full framework usage (routing, DI, middleware, SQS/jobs, testing), see docs/framework-usage.md.