Browse Source
- Add Product Requirements Document (PRD.md) with P0-P3 user stories - Add Roadmap.md with future ideas and lessons learned - Add .specify/memory/constitution.md with FastAPI principles Co-Authored-By: Claude Opus 4.6 <[email protected]>pull/14976/head
Santosh Bhavani
5 months ago
3 changed files with 302 additions and 0 deletions
@ -0,0 +1,83 @@ |
|||||
|
<!-- |
||||
|
Sync Impact Report: |
||||
|
- Version change: N/A → 1.0.0 (initial creation) |
||||
|
- New constitution - no prior version |
||||
|
- Added sections: 5 core principles, 2 additional sections, governance |
||||
|
- Templates requiring updates: N/A - this is the initial version |
||||
|
--> |
||||
|
|
||||
|
# FastAPI Constitution |
||||
|
|
||||
|
## Core Principles |
||||
|
|
||||
|
### I. Standards-Based |
||||
|
|
||||
|
FastAPI MUST be built on open standards for APIs. All features MUST support OpenAPI (formerly Swagger) and JSON Schema. The framework MUST generate compliant API documentation automatically. Rationale: Ensures interoperability and automatic tooling support (client generation, documentation). |
||||
|
|
||||
|
### II. Type Safety (NON-NEGOTIABLE) |
||||
|
|
||||
|
FastAPI MUST leverage Python type hints for request validation, response serialization, and automatic documentation. Type checking MUST pass with mypy at strict level. Rationale: Catches bugs at development time, enables IDE autocomplete, powers automatic documentation. |
||||
|
|
||||
|
### III. Test-First Development |
||||
|
|
||||
|
All new features MUST have tests written before implementation. The framework MUST maintain comprehensive test coverage. Tests MUST verify both functionality and API contract compliance. Rationale: FastAPI is a framework used in production by millions; regressions are costly. |
||||
|
|
||||
|
### IV. Performance |
||||
|
|
||||
|
FastAPI MUST achieve performance comparable to NodeJS and Go frameworks. Async support MUST be first-class with no performance penalty for sync code paths. Rationale: Performance is a primary feature claim; benchmarks MUST remain competitive. |
||||
|
|
||||
|
### V. Developer Experience |
||||
|
|
||||
|
The framework MUST provide intuitive APIs with minimal boilerplate. Error messages MUST be clear and actionable. Documentation MUST include runnable examples. Rationale: "Fast to code" is a core value proposition; reduces developer cognitive load. |
||||
|
|
||||
|
## Additional Constraints |
||||
|
|
||||
|
### Technology Stack |
||||
|
|
||||
|
- **Language**: Python 3.8+ (subject to Python release support policy) |
||||
|
- **Core Dependencies**: Starlette for routing, Pydantic for data validation |
||||
|
- **Async**: First-class support for asyncio |
||||
|
- **Standards**: OpenAPI 3.0+, JSON Schema |
||||
|
|
||||
|
### Compatibility |
||||
|
|
||||
|
- **Python Versions**: Support Python versions according to PEP 594 |
||||
|
- **Breaking Changes**: Follow semantic versioning; MAJOR version bumps require deprecation warnings in prior minor releases |
||||
|
- **Dependencies**: Pin minimal required versions; allow compatible updates |
||||
|
|
||||
|
## Development Workflow |
||||
|
|
||||
|
### Code Quality Gates |
||||
|
|
||||
|
- All PRs MUST pass type checking (mypy --strict) |
||||
|
- All PRs MUST maintain or increase test coverage |
||||
|
- All PRs MUST include documentation for new features |
||||
|
- All PRs MUST pass CI/CD pipeline (lint, test, coverage) |
||||
|
|
||||
|
### Contribution Process |
||||
|
|
||||
|
1. Fork and create feature branch |
||||
|
2. Write tests first (must fail) |
||||
|
3. Implement feature |
||||
|
4. Ensure tests pass and coverage maintained |
||||
|
5. Update documentation |
||||
|
6. Submit PR with description |
||||
|
|
||||
|
### Release Process |
||||
|
|
||||
|
- Follow semantic versioning strictly |
||||
|
- Maintain changelog |
||||
|
- Publish release notes |
||||
|
- Ensure backwards compatibility within MAJOR version |
||||
|
|
||||
|
## Governance |
||||
|
|
||||
|
The FastAPI Constitution supersedes all other development practices. Amendments to this constitution MUST be documented with: |
||||
|
|
||||
|
1. Rationale for the change |
||||
|
2. Impact assessment on existing workflows |
||||
|
3. Migration plan if applicable |
||||
|
|
||||
|
All PRs and code reviews MUST verify compliance with these principles. Complexity MUST be justified against simpler alternatives. |
||||
|
|
||||
|
**Version**: 1.0.0 | **Ratified**: 2026-02-23 | **Last Amended**: 2026-02-23 |
||||
@ -0,0 +1,170 @@ |
|||||
|
# PRD: FastAPI Framework |
||||
|
|
||||
|
FastAPI is a modern, high-performance Python web framework for building APIs with Python type hints. This document outlines the product requirements for the FastAPI framework itself. |
||||
|
|
||||
|
## Implementation Status |
||||
|
|
||||
|
The core framework is mature and well-established. This PRD tracks major feature initiatives and improvements beyond the stable release. |
||||
|
|
||||
|
## User Stories |
||||
|
|
||||
|
### P0: Core Framework (Must Have) — ✅ Complete |
||||
|
|
||||
|
**As a** Python developer, |
||||
|
**I want** to build APIs quickly using type hints, |
||||
|
**So that** I get automatic validation, documentation, and IDE support. |
||||
|
|
||||
|
- [P0-US1] ✅ Route definition via decorators with path parameters |
||||
|
- [P0-US2] ✅ Query, header, and cookie parameter extraction with type hints |
||||
|
- [P0-US3] ✅ Request body validation using Pydantic models |
||||
|
- [P0-US4] ✅ Automatic OpenAPI schema generation |
||||
|
- [P0-US5] ✅ Interactive API documentation (Swagger UI + ReDoc) |
||||
|
- [P0-US6] ✅ Dependency injection system |
||||
|
- [P0-US7] ✅ Error handling with custom exception handlers |
||||
|
- [P0-US8] ✅ Response model typing with automatic serialization |
||||
|
|
||||
|
**Acceptance Criteria:** |
||||
|
- All core HTTP methods supported (GET, POST, PUT, DELETE, PATCH, OPTIONS) |
||||
|
- Type hints enable validation and documentation without boilerplate |
||||
|
- OpenAPI 3.0+ compliant schema generation |
||||
|
|
||||
|
### P1: Async & Performance (Must Have) — ✅ Complete |
||||
|
|
||||
|
**As a** developer building high-throughput APIs, |
||||
|
**I want** first-class async support, |
||||
|
**So that** I can handle many concurrent connections efficiently. |
||||
|
|
||||
|
- [P1-US1] ✅ Async route handlers with `async def` |
||||
|
- [P1-US2] ✅ Background tasks for deferred processing |
||||
|
- [P1-US3] ✅ WebSocket support for real-time communication |
||||
|
- [P1-US4] ✅ Middleware stack (request/response processing) |
||||
|
- [P1-US5] ✅ Sub-application mounting for modular apps |
||||
|
|
||||
|
**Acceptance Criteria:** |
||||
|
- Async handlers perform comparably to Node.js/Go |
||||
|
- WebSocket connections maintained efficiently |
||||
|
- Middleware applies correctly to all routes |
||||
|
|
||||
|
### P1: Security & Authentication (Should Have) — ✅ Complete |
||||
|
|
||||
|
**As a** developer building secure APIs, |
||||
|
**I want** built-in authentication and authorization, |
||||
|
**So that** I don't have to implement common patterns from scratch. |
||||
|
|
||||
|
- [P1-US6] ✅ OAuth2 password flow implementation |
||||
|
- [P1-US7] ✅ JWT token support |
||||
|
- [P1-US8] ✅ CORS middleware |
||||
|
- [P1-US9] ✅ HTTP Basic Auth |
||||
|
- [P1-US10] ✅ Dependency-based authorization scopes |
||||
|
|
||||
|
**Acceptance Criteria:** |
||||
|
- OAuth2 with JWT tokens works out of the box |
||||
|
- Security schemes documented in OpenAPI spec |
||||
|
|
||||
|
### P2: Developer Experience (Should Have) — ✅ Complete |
||||
|
|
||||
|
**As a** FastAPI user, |
||||
|
**I want** excellent tooling and error messages, |
||||
|
**So that** I can develop quickly and debug easily. |
||||
|
|
||||
|
- [P2-US1] ✅ FastAPI CLI for running and generating projects |
||||
|
- [P2-US2] ✅ Clear validation error messages with field locations |
||||
|
- [P2-US3] ✅ Static type checking support with mypy |
||||
|
- [P2-US4] ✅ Response model documentation in OpenAPI |
||||
|
|
||||
|
**Acceptance Criteria:** |
||||
|
- CLI provides `fastapi dev` and `fastapi run` |
||||
|
- Error responses include details for each validation failure |
||||
|
- Type hints work with pyright/mypy |
||||
|
|
||||
|
### P2: Extensibility (Should Have) — ✅ Complete |
||||
|
|
||||
|
**As a** framework contributor, |
||||
|
**I want** to extend FastAPI without modifying core code, |
||||
|
**So that** I can add custom behaviors. |
||||
|
|
||||
|
- [P2-US5] ✅ Custom response classes |
||||
|
- [P2-US6] ✅ Custom parameter types |
||||
|
- [P2-US7] ✅ Custom middleware interfaces |
||||
|
- [P2-US8] ✅ OpenAPI extension hooks |
||||
|
|
||||
|
**Acceptance Criteria:** |
||||
|
- Extensions integrate seamlessly with FastAPI |
||||
|
- Custom components documented in OpenAPI |
||||
|
|
||||
|
### P3: Advanced Features (Could Have) — ✅ Complete |
||||
|
|
||||
|
**As an** advanced user, |
||||
|
**I want** sophisticated deployment options, |
||||
|
**So that** I can optimize for production. |
||||
|
|
||||
|
- [P3-US1] ✅ Testing utilities with TestClient |
||||
|
- [P3-US2] ✅ Dependency overrides for testing |
||||
|
- [P3-US3] ✅ ASGI server integration (Uvicorn, Hypercorn) |
||||
|
- [P3-US4] ✅ Gunicorn worker support |
||||
|
- [P3-US5] ✅ Docker integration and multi-stage builds |
||||
|
|
||||
|
**Acceptance Criteria:** |
||||
|
- Testing patterns documented and working |
||||
|
- Production deployment guides available |
||||
|
|
||||
|
## Architecture: Starlette + Pydantic |
||||
|
|
||||
|
FastAPI builds on two key libraries: |
||||
|
|
||||
|
| Component | Role | |
||||
|
|-----------|------| |
||||
|
| Starlette | Routing, middleware, ASGI handler | |
||||
|
| Pydantic | Data validation, serialization, OpenAPI generation | |
||||
|
|
||||
|
### Request/Response Flow |
||||
|
|
||||
|
``` |
||||
|
Request → ASGI Handler → Middleware → Route Handler → Dependency Injection |
||||
|
↓ |
||||
|
Response ← Serialization ← Pydantic Model ← Return Value |
||||
|
``` |
||||
|
|
||||
|
### Key Components |
||||
|
|
||||
|
| Component | File | Role | |
||||
|
|-----------|------|------| |
||||
|
| FastAPI app | `fastapi/applications.py` | Main application class | |
||||
|
| Routing | `fastapi/routing.py` | Route resolution, OpenAPI generation | |
||||
|
| Dependencies | `fastapi/dependencies.py` | Dependency injection system | |
||||
|
| Params | `fastapi/params.py` | Parameter definitions | |
||||
|
| Response | `fastapi/response.py` | Response handling | |
||||
|
| OpenAPI | `fastapi/openapi/` | Schema generation | |
||||
|
|
||||
|
## Non-Functional Requirements |
||||
|
|
||||
|
### Performance |
||||
|
- Request/response latency comparable to Node.js and Go |
||||
|
- Minimal overhead for sync handlers |
||||
|
- Efficient async task scheduling |
||||
|
|
||||
|
### Compatibility |
||||
|
- Python 3.8+ (subject to PEP 594) |
||||
|
- OpenAPI 3.0+ and JSON Schema |
||||
|
- ASGI specification compliance |
||||
|
|
||||
|
### Security |
||||
|
- Input validation via Pydantic |
||||
|
- Secure defaults for authentication |
||||
|
- No sensitive data in error messages |
||||
|
|
||||
|
### Reliability |
||||
|
- Comprehensive test coverage |
||||
|
- Deprecation warnings for breaking changes |
||||
|
- Stable API surface within major versions |
||||
|
|
||||
|
## Test Scenarios |
||||
|
|
||||
|
1. **Basic API**: Create endpoint, verify request/response |
||||
|
2. **Validation**: Send invalid data, verify 422 error with details |
||||
|
3. **Async**: Test async handler with concurrent requests |
||||
|
4. **Dependencies**: Verify dependency injection ordering |
||||
|
5. **Auth**: Test OAuth2 flow end-to-end |
||||
|
6. **Documentation**: Verify OpenAPI schema accuracy |
||||
|
7. **Middleware**: Test request/response modification |
||||
|
8. **Sub-app**: Mount app, verify routing isolation |
||||
@ -0,0 +1,49 @@ |
|||||
|
# Roadmap |
||||
|
|
||||
|
Future enhancements and improvements for the FastAPI framework. |
||||
|
|
||||
|
## Completed |
||||
|
|
||||
|
All P0–P3 user stories from the original PRD are implemented. See [PRD.md](PRD.md) for details. |
||||
|
|
||||
|
Key milestones achieved: |
||||
|
- Core routing with type hints and automatic validation |
||||
|
- Async support with first-class performance |
||||
|
- OAuth2, JWT, and security utilities |
||||
|
- FastAPI CLI and developer tooling |
||||
|
- Extensibility via custom components |
||||
|
- Comprehensive testing utilities |
||||
|
- Production deployment options |
||||
|
|
||||
|
## Ideas (Unprioritized) |
||||
|
|
||||
|
These are potential directions. None have user stories or acceptance criteria yet — they need to be scoped before work begins. |
||||
|
|
||||
|
- **Improved Error Messages**: More helpful validation errors with suggestions |
||||
|
- **Typed Middleware**: Type-safe middleware definitions |
||||
|
- **Enhanced OpenAPI**: More detailed schema generation options |
||||
|
- **Plugin System**: Formal extension mechanism for third-party integrations |
||||
|
- **Native gRPC Support**: gRPC reflection and transcoding |
||||
|
- **GraphQL Integration**: More mature GraphQL schema generation |
||||
|
- **Better Type Inference**: Improved type hints for complex scenarios |
||||
|
- **Streaming Responses**: Native support for Server-Sent Events |
||||
|
- **HTTP/2 Support**: Push promises and header compression |
||||
|
- **Zero-Config Deployments**: Simplified production setup |
||||
|
|
||||
|
## Won't Have |
||||
|
|
||||
|
- **Built-in Database ORM**: Users should choose their own (SQLAlchemy, Prisma, etc.) |
||||
|
- **Built-in Authentication Provider**: Identity management is outside framework scope |
||||
|
- **Template Engine**: Use external libraries (Jinja2, etc.) directly |
||||
|
- **Full-Stack Framework**: FastAPI remains focused on APIs only |
||||
|
|
||||
|
## Lessons Learned |
||||
|
|
||||
|
From years of maintaining FastAPI as a community-driven framework: |
||||
|
|
||||
|
1. **Good**: Type hints provide excellent developer experience and IDE support |
||||
|
2. **Good**: OpenAPI integration enables rich ecosystem (clients, docs, testing) |
||||
|
3. **Good**: Dependency injection promotes loose coupling and testability |
||||
|
4. **Issue**: Balancing new features with stability is challenging |
||||
|
5. **Fix**: Semantic versioning with clear deprecation paths |
||||
|
6. **Fix**: Comprehensive documentation with examples |
||||
Loading…
Reference in new issue