api-design

# API Design ## Core Principles - **Contract-First** — Define API spec before implementation - **OpenAPI 3.2** — Use OpenAPI for REST API documentation - **URL Versioning** — Version in path `/v1/`, with Sunset headers - **Idempotency** — PUT/DELETE must be idempotent, POST uses Idempotency-Key - **Cursor Pagination** — Avoid offset-based pagination - **RFC 7807 Errors** — Standard Problem Details format - **No backwards compatibility** — Delete, don't deprecate --- ## Quick Reference ### When to Use What | Scenario | Choice | Reason | |----------|--------|--------| | Public API / MVP | REST | Simple, universal, easy debugging | | Frontend-driven / Mobile | GraphQL | Fetch exactly what you need | | Microservices internal | gRPC | High performance, strong typing | | Real-time data | gRPC / GraphQL Subscriptions | Bidirectional streaming | --- ## REST API Design ### Resource Naming ``` # Good GET /users # List users GET /users/123 # Get user POST /users # Create user PUT /users/123 # Replace user PATCH /users/123 # Update user DELETE /users/123 # Delete user # Nested resources GET /users/123/orders # User's orders # Actions (when CRUD doesn't fit) POST /users/123/activate # Action on resource # Query parameters for filtering GET /users?status=active&role=admin&limit=20 ``` ### HTTP Methods | Method | Purpose | Idempotent | Safe | |--------|---------|------------|------| | GET | Read | Yes | Yes | | ...