Fastapi Expert

FastAPI Expert: API Excellence

"Fast, easy to learn, fast to code, ready for production." - This skill ensures your FastAPI code actually lives up to that promise.

🔒 Prerequisites (Mandatory)

This skill operates WITHIN the SDD framework. Before starting any technical execution: 0. Mode Check: Verify the current operational mode (.hub-mode) and apply the token-distiller skill guidelines.

1. Context Check: Rehydrate state by reading .specs/project/STATE.md, .specs/project/MEMORY.md, and .specs/project/LEARNINGS.md.
2. Spec Check: Does the spec.md file exist with clear requirements and Acceptance Criteria (ACs)? (BDD mandatory for Medium+).
3. Plan Check: Does the plan.md file define the architecture, schemas, and include Mermaid diagrams?
4. Contract Check: Was the contract.md file established with validation sensors?
5. Task Check: Is the task list in .specs/project/tasks.md (or feature-specific) detailed and atomized?

Goal

Provide a decision and implementation framework for high-performance APIs, ensuring the correct use of Dependency Injection, Strict Typing (Annotated), and native integration with the python-uv ecosystem.

Workflow (6 Phases)

Phase 0: ARCHITECTURE_DESIGN

Define the project structure (Clean Architecture).

• Rule: Decide between Repository Pattern or Service Layer before coding.
• Reference: See Architecture Guide.

Phase 1: SCHEMA_DESIGN

Define data contracts using Pydantic V2.

• Rule: NEVER use RootModel. Prefer TypeAdapter or structured models.
• Mandate: Every field must have Field(description=...) for automatic documentation.

Phase 2: DEPENDENCY_ARCHITECTURE

Map dependencies and security (JWT).

• Rule: Exclusively use Annotated[Type, Depends(func)].
• Logic: Create aliases for reusable dependencies.

Phase 3: IMPLEMENTATION & ERROR_HANDLING

Write endpoints and exception handlers.

• Rule: Use async def only for truly asynchronous I/O operations.
• Mandate: Implement global handlers for domain exceptions.

Phase 4: VALIDATION & PERF

Performance audit and documentation.

• Check: Validate that there is no blocking code inside async def.
• Mandate: Perform performance audits using standardized benchmarking tools and document results.

Phase 5: TESTING

Implement unit and integration tests.

• Rule: Ensure 100% coverage in critical services with Pytest.

Key Patterns (The FastAPI Standard)

1. Annotated Style (Mandatory)

from typing import Annotated
from fastapi import Depends, Path

# DO THIS
async def read_item(item_id: Annotated[int, Path(title="The ID of the item")]):
    ...

# NOT THIS
async def read_item(item_id: int = Path(...)):
    ...

2. UV Integration

Always initialize and manage dependencies via python-uv:

uv add fastapi pydantic-settings
uv run fastapi dev main.py

Quality Rules

• Clean Code: Follow SOLID principles. Endpoints should be "thin" (logic in services/dependencies).
• Security: Utilize OAuth2PasswordBearer and scopes for access control.
• Performance: Pydantic V2 (Rust core) must be the sole source of serialization.

Prohibited

• NEVER use ... (Ellipsis) in Pydantic models or mandatory parameters.
• NEVER mix database logic directly in the endpoint (use Dependencies instead).
• NEVER use deprecated serialization libraries (ujson/orjson).

Output Structure

Execution of this skill should result in APIs that follow this recommended file structure:

Detailed References

For a deep dive into each topic, consult the specialized guides:

version: "2.3.0"
feature_id: "HUB-ALIGNMENT"
phase: "VERIFY"
status: "COMPLETED"
last_update: "2026-05-06T13:16:19.359394Z"
evidence_checksum: "8e52f6a"