Django Template for Public REST APIs

This is a template for creating a public REST API using Django, Django Ninja, and AWS Lambda with API Gateway. It is intended to be used as a starting point for new projects.

Overview

This template is written in Python 3.9 and uses the Django Ninja framework for handling HTTP requests/responses. Our API is stateless, has no database, and is intended to run ephemerally on serverless environments (currently AWS Lambda via API Gateway v2). We achieve this by wrapping our ASGI application with Mangum, an ASGI adapter for AWS Lambda. You can still develop locally by running Django's built-in development server.

Setup

1. Create a new repository from this template and clone it!
2. Create and activate a virtual environment: python -m venv .venv && source .venv/bin/activate
3. Install dependencies with pip install -r requirements-dev.txt.
4. Create .envrc via cp .envrc.example .envrc and fill in the necessary environment variables. This file type assumes you are using direnv to manage your environment variables. If you are not, export the variables in your shell or use a different method.
5. Start your local server with python -m django runserver --settings=app.settings.
6. Start developing!

Development

Enable git hooks by running pre-commit install --hook-type pre-commit --hook-type pre-push in the root of your project.

On every commit:

• ruff format — formats code (Black-compatible)
• ruff check --fix — lints and auto-fixes imports, style, annotations, and more

On every push:

• pytest — runs the full test suite and blocks the push if any tests fail

You can also run these manually at any time:

ruff format app/ specs/   # format
ruff check app/ specs/    # lint
pytest                    # test
pytest --cov=app --cov-report term  # test with coverage

Important things to note: