---
name: python-rest-api-architect
description: "Lays out a complete Python REST API project in Flask, FastAPI, or Django REST Framework: directory tree, every source file, a README, and an OpenAPI spec when requested, shaped to your auth and database choices. Use when a whole Python REST API project in Flask, FastAPI, or Django REST Framework must be generated with auth, a database, and optionally an OpenAPI spec and async views. Do not use for a single FastAPI endpoint, or a Flask-only scaffold with blueprints and CORS. Related topics: coding, python."
---

# Python REST API Architect

Lays out a complete Python REST API project in Flask, FastAPI, or Django REST Framework: directory tree, every source file, a README, and an OpenAPI spec when requested, shaped to your auth and database choices.

## When to use

Use this skill when a whole Python REST API project in Flask, FastAPI, or Django REST Framework must be generated with auth, a database, and optionally an OpenAPI spec and async views. Do not use it for a single FastAPI endpoint, or a Flask-only scaffold with blueprints and CORS.

## Workflow

1. Ask the user for each input listed below in a single message, skipping any they have already given. Where options are listed, offer them, but accept other answers too.
2. Lay out the directory tree in the convention of the chosen framework so the structure is recognizable.
3. Derive models and schemas or serializers from the resources named in the endpoint list.
4. Implement every endpoint with correct status codes and one shared validation error shape, honoring the async toggle where the framework allows.
5. Add the chosen auth as a dependency or decorator on every non-public endpoint, including the route that issues credentials.
6. Write the README with install and run steps and generate or hand-write the OpenAPI spec when requested, then output the full document.

## Inputs

- **Framework** (choose one: Flask, FastAPI, Django Rest Framework)
- **Authentication method** (choose one: JWT, OAuth2, API Key, None)
- **Database type** (choose one: PostgreSQL, MySQL, SQLite, MongoDB, None)
- **Endpoint definitions** (longer free text)
- **Include OpenAPI spec** (choose one: Yes, No)
- **Use async** (choose one: Yes, No)

## Output

One markdown document: directory tree, full source of every file in fenced blocks with language tags, a concise README with install and run steps, and the OpenAPI spec when requested.

## Prompt template

Fill the inputs into this template and follow it as the full instruction.

### Python REST API Architect

Produce a ready-to-run REST API project from this specification.

- Framework: {{Framework}}
- Authentication method: {{Authentication method}}
- Database type: {{Database type}}
- Endpoint definitions: {{Endpoint definitions}}
- Include OpenAPI spec: {{Include OpenAPI spec}}
- Use async: {{Use async}}

Choose the project layout the framework community expects (a package with an app factory for Flask, routers and dependencies for FastAPI, apps with serializers and viewsets for Django Rest Framework) so a new hire recognizes it. Derive the models from the endpoints: every resource in a path gets a model and, where the framework has them, a schema or serializer. Implement each listed endpoint with the right status codes and a validation error shape shared across routes. Honor the async toggle only where the framework supports it (FastAPI natively, Flask with async views, Django with async views and an async-capable driver), and say when a chosen database driver forces sync. Implement the chosen auth as a dependency or decorator used by every non-public endpoint, with the token-issuing route included. Point configuration at environment variables with sensible local defaults for the chosen database. For the OpenAPI spec, generate it from the framework when it can (FastAPI, drf-spectacular) and write it by hand only for Flask. Return one markdown document with: the directory tree, the full source of every file in fenced blocks with language tags, a concise README with install and run steps, and the OpenAPI file when requested.

## Pitfalls

- Declaring async views on top of a synchronous database driver, which blocks the event loop and performs worse than sync.
- Hand-writing an OpenAPI file for FastAPI or DRF that drifts from the one the framework already generates.
- Leaving the token-issuing route out, so the auth dependency can never be satisfied.
