playbooks

home / skills / eyadsibai / ltk / fastapi

fastapi skill

/plugins/ltk-engineering/skills/python/fastapi

This skill helps you design FastAPI APIs with proper routing, dependency injection, Pydantic models, and error handling for reliable apps.

npx playbooks add skill eyadsibai/ltk --skill fastapi

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
4.9 KB
---
name: FastAPI
description: This skill should be used when the user asks about "FastAPI", "FastAPI routes", "FastAPI dependencies", "Pydantic models", "FastAPI middleware", "API endpoints", "OpenAPI", or mentions FastAPI development.
version: 1.0.0
---

# FastAPI Development

Guidance for building APIs with FastAPI following best practices.

---

## Core Concepts

### Route Decorators

| Decorator | HTTP Method | Use Case |
|-----------|-------------|----------|
| `@app.get()` | GET | Retrieve data |
| `@app.post()` | POST | Create resource |
| `@app.put()` | PUT | Full update |
| `@app.patch()` | PATCH | Partial update |
| `@app.delete()` | DELETE | Remove resource |

### Response Status Codes

| Code | Meaning | When to Use |
|------|---------|-------------|
| **200** | OK | Successful GET/PUT/PATCH |
| **201** | Created | Successful POST |
| **204** | No Content | Successful DELETE |
| **400** | Bad Request | Invalid input |
| **401** | Unauthorized | Authentication required |
| **403** | Forbidden | No permission |
| **404** | Not Found | Resource doesn't exist |
| **422** | Unprocessable | Validation failed |

---

## Dependency Injection

**Key concept**: Dependencies are functions that FastAPI calls before your route handler. Use `yield` for cleanup logic.

| Pattern | Use Case |
|---------|----------|
| **Simple function** | Get config, compute values |
| **Generator (yield)** | Database sessions, connections |
| **Class-based** | Complex dependencies with state |
| **Nested dependencies** | Dependencies that depend on other dependencies |

### Common Dependencies

| Dependency | Purpose |
|------------|---------|
| **get_db** | Database session (yield for cleanup) |
| **get_current_user** | Authentication + user retrieval |
| **get_settings** | Configuration singleton |
| **rate_limiter** | Request throttling |

**Key concept**: Use `Annotated[Type, Depends(func)]` for cleaner type hints and reusability.

---

## Pydantic Models

### Model Patterns

| Pattern | Purpose |
|---------|---------|
| **Base model** | Shared fields |
| **Create model** | Input for POST (no id) |
| **Update model** | Partial updates (all Optional) |
| **Response model** | Output (includes id, timestamps) |
| **DB model** | Internal with `from_attributes = True` |

### Validation Features

| Feature | Purpose |
|---------|---------|
| **Field(...)** | Required with constraints |
| **Field(default=...)** | Optional with default |
| **field_validator** | Custom validation logic |
| **model_validator** | Cross-field validation |
| **pattern=** | Regex validation |
| **ge=, le=** | Numeric bounds |
| **min_length=, max_length=** | String/list length |

---

## Error Handling

| Approach | Use Case |
|----------|----------|
| **HTTPException** | Simple errors with status code |
| **Custom exception class** | Structured error responses |
| **@app.exception_handler** | Global error handling |
| **RequestValidationError** | Customize validation errors |

**Key concept**: Create custom exception classes for consistent error response format across your API.

---

## Router Organization

| Concept | Purpose |
|---------|---------|
| **APIRouter** | Group related endpoints |
| **prefix** | URL prefix for all routes |
| **tags** | OpenAPI documentation grouping |
| **dependencies** | Router-level dependencies |

### Project Structure

| Directory | Contents |
|-----------|----------|
| **routers/** | Route handlers by domain |
| **models/** | SQLAlchemy/database models |
| **schemas/** | Pydantic request/response models |
| **services/** | Business logic |
| **dependencies.py** | Shared dependencies |
| **config.py** | Settings and configuration |

---

## Background Tasks

| Method | Use Case |
|--------|----------|
| **BackgroundTasks** | Simple async tasks (email, logging) |
| **Celery** | Heavy tasks, retries, scheduling |
| **ARQ** | Async Redis queue |

**Key concept**: BackgroundTasks run after response is sent—good for non-critical operations that shouldn't block the response.

---

## Testing Patterns

| Client | Use Case |
|--------|----------|
| **TestClient** | Sync tests (most common) |
| **AsyncClient (httpx)** | Async tests, lifespan events |

### Dependency Override Pattern

1. Create test version of dependency
2. Set `app.dependency_overrides[original] = test_version`
3. Run tests
4. Clear overrides after

**Key concept**: Override `get_db` for test database, `get_current_user` for auth bypass.

---

## Best Practices

| Practice | Why |
|----------|-----|
| Use response_model | Control output, hide internal fields |
| Use dependency injection | Testable, reusable code |
| Separate schemas from DB models | Decouple API from database |
| Use routers for organization | Maintainable as API grows |
| Add OpenAPI descriptions | Self-documenting API |
| Use async for I/O | Better concurrency |

## Resources

- Docs: <https://fastapi.tiangolo.com/>
- Tutorial: <https://fastapi.tiangolo.com/tutorial/>

Overview

This skill provides practical guidance for building robust APIs with FastAPI, covering routes, dependency injection, Pydantic models, error handling, testing, and project organization. It focuses on patterns and best practices that produce maintainable, well-documented, and testable APIs.

How this skill works

The skill inspects common FastAPI concepts and translates them into actionable patterns: route decorators and status codes, dependency types and lifecycle, Pydantic model patterns and validators, router organization, background tasks, and testing patterns. It highlights when to use built-in tools like BackgroundTasks, dependency overrides for tests, and response_model to control outputs.

When to use it

  • When defining REST endpoints and choosing proper HTTP methods and status codes
  • When designing request/response schemas with Pydantic and validation rules
  • When implementing shared services like database sessions, auth, or rate limiting
  • When organizing a growing API into routers, services, and schemas
  • When writing tests that need dependency overrides or test databases
  • When adding background processing or integrating task queues

Best practices

  • Use response_model to control output and hide internal fields
  • Keep Pydantic schemas separate from DB models to decouple API and storage
  • Use dependency injection for reusable, testable components and use yield for cleanup
  • Group endpoints with APIRouter, set prefixes and tags for clear OpenAPI docs
  • Prefer async for I/O-bound operations and use BackgroundTasks for non-blocking work
  • Override dependencies during tests (app.dependency_overrides) and restore after

Example use cases

  • Create a user resource: POST /users with Create model, return 201 and Response model
  • Protect routes with get_current_user dependency and return 401/403 appropriately
  • Provide a DB session via get_db using yield for automatic cleanup
  • Organize billing endpoints in routers/billing.py with prefix '/billing' and shared dependencies
  • Write tests with TestClient and a test get_db override to use an in-memory database
  • Run email sending after signup using BackgroundTasks or push to Celery for heavy jobs

FAQ

When should I use yield in a dependency?

Use yield for dependencies that need cleanup after the request, such as database sessions or connections.

How do I validate cross-field constraints in Pydantic?

Use model_validator (or root_validator in older versions) for cross-field checks and raise ValueError for invalid combinations.