# Project P3 — Production REST API By the end of this chapter you will: - Ship a multi-resource REST API with auth, validation, and pagination - Back it with PostgreSQL, migrations, and a tested data layer - Package and deploy it with Docker and environment-based config - Prove quality: ≥80% coverage, CI passing, and a public URL --- ## The project goal Build and ship a production-grade API for a task and project workspace product. Core domain: - users, - projects, - tasks, - comments, - audit events. Core non-functional requirements: - JWT auth with role checks, - PostgreSQL persistence with Alembic migrations, - robust test suite, - containerized deployment, - operational runbook. --- ## What success looks like Minimum acceptance criteria: 1. Public API URL reachable and documented. 2. At least 20 endpoints across the domain. 3. Auth and authorization enforced consistently. 4. Migrations reproducible in fresh environment. 5. Automated tests with at least 80% coverage on core modules. 6. CI pipeline passing with lint, type checks, tests, and migration check. When you present this project, emphasize engineering decisions and tradeoffs, not only endpoint count. --- ## Recommended architecture ```text app/ api/ routers/ auth.py projects.py tasks.py comments.py services/ auth_service.py project_service.py task_service.py repositories/ project_repo.py task_repo.py db/ session.py models.py schemas/ auth.py project.py task.py core/ config.py security.py tests/ api/ services/ repositories/ migrations/ ``` Layer responsibilities: - routers: transport and request/response contracts, - services: business rules and orchestration, - repositories: persistence queries, - schemas: boundary contracts, - db/core: infrastructure primitives. --- ## Implementation plan Phase 1: Skeleton and core infrastructure - Initialize FastAPI app with config and structured logging. - Add SQLAlchemy engine/session and base models. - Configure Alembic and create initial migration. - Add health and readiness endpoints. Phase 2: Authentication and authorization - User registration and login endpoints. - Password hashing and token issuance. - Refresh token strategy and role guards. - Auth tests for valid, invalid, and expired token paths. Phase 3: Domain workflows - Project CRUD with ownership rules. - Task CRUD with status transitions and assignment rules. - Comment endpoints scoped by project membership. - Pagination, filtering, and sorting for list routes. Phase 4: Quality and security hardening - Add input/output schema strictness. - Apply rate limiting to auth and expensive endpoints. - Add structured error responses and request correlation id. - Expand negative-path tests and dependency audit checks. Phase 5: Deployment and release - Build multi-stage Docker image. - Apply migrations in deployment pipeline. - Run smoke tests post-deploy. - Document rollback and incident-response steps. --- ## Command runbook ```bash # local dev uvicorn app.main:app --reload # migrations alembic revision --autogenerate -m "initial schema" alembic upgrade head # tests pytest -q # coverage pytest --cov=app --cov-report=term-missing # docker docker build -t p3-rest-api:latest . docker run --rm -p 8000:8000 --env-file .env p3-rest-api:latest ``` --- ## Quality gates | Gate | Requirement | |---|---| | Lint/format | passing | | Type checks | passing (no critical suppressions) | | Unit/integration tests | passing | | Coverage | at least 80% in core modules | | Migration check | clean upgrade on empty and seeded DB | | Security check | dependency audit with no unresolved critical issues | --- ## Common failure modes | Failure mode | Symptom | Fix | |---|---|---| | Missing migration in deploy | app crashes on startup query | run migration gate before release | | Weak auth boundary in service layer | cross-user data exposure | enforce ownership checks in services | | No transaction rollback on write errors | stuck session state | rollback and map errors to API semantics | | Test suite only happy path | regressions slip to prod | add negative and authz path coverage | | Undocumented operational steps | difficult incident response | maintain runbook with explicit commands | --- ## Extension ideas 1. Add websocket notifications for task updates. 2. Add caching for project list endpoints. 3. Add webhook delivery subsystem with retry policy. 4. Generate typed API clients from OpenAPI schema. 5. Add audit dashboard and anomaly alerts. --- ## ADR sample ### ADR-001: Repository pattern and SQLAlchemy sync sessions - Context: Team needs explicit separation between transport, business logic, and persistence. - Decision: Use repository pattern with sync SQLAlchemy sessions in request scope. - Consequences: - Positive: better test seams and cleaner service code. - Negative: additional boilerplate for repository interfaces. - Future revisit: evaluate async SQLAlchemy if throughput profile demands it. --- ## Interview defense prompts 1. Why did you choose this architecture over a single-layer route-only approach? 2. How does your auth system handle token revocation and role escalation risk? 3. How do you guarantee schema migration safety during deploy? 4. Which endpoint was the most performance-sensitive and how did you optimize it? 5. What would you change first if traffic increased 10x? --- ## Summary - P3 is the proof that you can ship, secure, and operate a production API. - Strong boundaries plus migration and test discipline matter more than framework novelty. - Deployment and rollback readiness are part of completion criteria. - The project is complete only when another engineer can run it from your runbook. ## Self-Check Quiz