api-design-patterns

| GET /v1/users | GET /v1/getUsers | No verbs — HTTP method implies action | | POST /v1/users | POST /v1/user/create | POST to collection = create | | GET /v1/order-items | GET /v1/orderItems | Kebab-case, not camelCase | | GET /v1/users/{id}/orders | GET /v1/users/{id}/orders/{oid}/items | Max 2 nesting levels |

| POST /v1/orders/{id}/actions/cancel | POST /v1/cancelOrder/{id} | Action sub-resource for non-CRUD |

| Method | Purpose | Request Body | Success Status | Idempotent |

Convenzioni di progettazione del contratto API per progetti FastAPI con Pydantic v2. Utilizzare durante la fase di progettazione quando si pianificano nuovi endpoint API, si definiscono contratti di richiesta/risposta, si progetta l'impaginazione o il filtraggio, si standardizzano le risposte agli errori o si pianifica il controllo delle versioni dell'API. Copre la denominazione RESTful, la semantica del metodo HTTP, le convenzioni di denominazione dello schema Pydantic v2 (XxxCreate/XxxUpdate/XxxResponse), l'impaginazione basata su cursore, il formato di errore standard e la documentazione OpenAPI. NON copre i dettagli di implementazione (usa python-backend-expert) o l'architettura a livello di sistema (usa l'architettura di sistema). Fonte: hieutrtr/ai1-skills.