SKILL.md--- name: api-route-design description: | Use when designing RESTful API endpoints in FastAPI or Python projects. Triggers for: creating GET/POST/PUT/DELETE endpoints, request validation with Pydantic, response formatting with JSON schemas, status code selection, pagination, filtering, or sorting parameters. NOT for: GraphQL APIs, WebSocket handlers, or non-RESTful endpoints. --- # API Route Design Skill Expert design and implementation of RESTful APIs with proper validation, response formatting, and HTTP semantics. ## Quick Reference | Pattern | Example | Purpose | |---------|---------|---------| | List resource | `@router.get("/fees/", response_model=List[FeeOut])` | Retrieve collection | | Get by ID | `@router.get("/fees/{fee_id}")` | Retrieve single resource | | Create | `@router.post("/fees/", response_model=FeeOut, status_code=201)` | Create new resource | | Update | `@router.put("/fees/{fee_id}")` | Full resource update | | Patch | `@router.patch("/fees/{fee_id}")` | Partial resource update | | Delete | `@router.delete("/fees/{fee_id}", status_code=204)` | Remove resource | ## URL Naming Conventions ``` /v1/{resource} # Collection endpoints /v1/{resource}/{id} # Single resource endpoints /v1/{resource}/{id}/sub # Nested resource endpoints ``` **Rules:** - Use lowercase, hyphens for multi-word: `/student-fees` not `/studentFees` - Use plural nouns for collections: `/users` not `/user` - Use HTTP methods semantically: GET (read), POST (create), PUT/PATCH (update), DELETE (remove) ## HTTP Status Codes | Code | Usage | Example | |------|-------|---------| | 200 | OK | Successful GET, PUT, PATCH | | 201 | Created | Successful POST (resource created) | | 202 | Accepted | Async operation started | | 204 | No Content | Successful DELETE | | 400 | Bad Request | Invalid input, validation failed | | 401 | Unauthorized | Missing or invalid auth | | 403 | Forbidden | Authenticated but not authorized | | 404 | Not Found | Resource doesn't exist | | 422 | Unprocessable Entity | Validation errors (Pydantic) | | 500 | Internal Server Error | Unexpected server error | ## Request Validation Patterns ### Path Parameters ```python from fastapi import APIRouter, HTTPException from typing import Annotated router = APIRouter() @router.get("/fees/{fee_id}") async def get_fee(fee_id: int): fee = await get_fee_by_id(fee_id) if not fee: raise HTTPException(status_code=404, detail="Fee not found") return fee ``` ### Query Parameters (Pagination, Filtering, Sorting) ```python @router.get("/fees/", response_model=List[FeeOut]) async def list_fees( skip: int = Query(0, ge=0), limit: int = Query(100, ge=1, le=1000), status: str | None = Query(None, pattern="^(pending|paid|overdue)$"), sort_by: str = Query("created_at", enum=["created_at", "amount", "due_date"]), sort_order: str = Query("desc", enum=["asc", "desc"]), ): return await paginate_fees( skip=skip, limit=limit, sta