api-design

# API Design Skills ## Overview API design knowledge for building clean, consistent, and developer-friendly APIs. This domain covers REST, GraphQL, gRPC, documentation standards, and best practices. ## API Types Comparison ``` ┌─────────────────────────────────────────────────────────────────────────────┐ │ API Types Comparison │ ├──────────────┬──────────────┬──────────────┬──────────────┬─────────────────┤ │ Aspect │ REST │ GraphQL │ gRPC │ Best For │ ├──────────────┼──────────────┼──────────────┼──────────────┼─────────────────┤ │ Protocol │ HTTP/1.1 │ HTTP/1.1 │ HTTP/2 │ │ │ Format │ JSON/XML │ JSON │ Protobuf │ │ │ Schema │ Optional │ Required │ Required │ │ │ │ (OpenAPI) │ (SDL) │ (.proto) │ │ │ Caching │ HTTP native │ Complex │ Manual │ │ │ Real-time │ Polling/SSE │ Subscriptions│ Streaming │ │ │ Learning │ Easy │ Medium │ Hard │ │ ├──────────────┼──────────────┼──────────────┼──────────────┼─────────────────┤ │ Use Cases │ Public APIs │ Flexible │ Microservices│ │ │ │ CRUD apps │ Mobile apps │ Low latency │ │ │ │ Web services │ Aggregation │ High perf │ │ └──────────────┴──────────────┴──────────────┴──────────────┴─────────────────┘ ``` ## Categories ### REST - REST principles and HATEOAS - Resource naming conventions - HTTP methods semantics - Status codes usage - Pagination strategies - Filtering and sorting - API versioning ### GraphQL - Schema design - Queries and mutations - Resolvers - Subscriptions - N+1 problem solutions ### gRPC - Protocol Buffers - Service definitions - Streaming patterns - Error handling ### Documentation - OpenAPI/Swagger - API documentation best practices - Examples and SDKs ### Patterns - Request/Response design - Error handling - Authentication patterns - Rate limiting - Idempotency ### Best Practices - API design guidelines - Backwards compatibility - API evolution strategies ## REST Maturity Model (Richardson) ``` ┌─────────────────────────────────────────────────────────────────┐ │ REST Maturity Model │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ Level 3: Hypermedia Controls (HATEOAS) │ │ ├── Self-documenting APIs │ │ ├── Discoverability via links │ │ └── Decoupled client-server evolution │ │ ↑ │ │ Level 2: HTTP Verbs + Status Codes │ │ ├── GET, POST, PUT, PATCH, DELETE │ │ ├── Proper status codes (200, 201, 404, etc.) │ │ └── Safe and idempotent methods │ │ ↑ │ │ Level 1: Resources │ │ ├── Multiple URIs for different resources │ │ ├── /users, /orders, /products │ │ └── Still using single HTTP verb │ │ ↑ │ │ Level 0: The Swamp of POX │ │ ├── Single URI for all operations │ │ ├── POST /api with action in body │ │ └── RPC-style over HTTP │ │ │ └─────────────────────────────────────────────────────────────────┘ ``` ## API Design Decision Tree ``` ┌─────────────────────────────────────────────────────────────────┐ │ Which API Style to Choose? │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ Start Here │ │ │ │ │ ▼ │ │ Public API for third parties? │ │ │ │ │ ├── Yes → REST (with OpenAPI) │ │ │ • Easy to understand │ │ │ • Good tooling │ │ │ • HTTP caching │ │ │ │ │ └── No → Internal/Microservices? │ │ │ │ │ ├── Yes → Need real-time? │ │ │ │ │ │ │ ├── Yes → gRPC streaming │ │ │ │ │ │ │ └── No → High performance? │ │ │ │ │ │ │ ├── Yes → gRPC │ │ │ └── No → REST │ │ │ │ │ └── No → Mobile/Web frontend? │ │ │ │ │ ├── Multiple clients? → GraphQL │ │ ├── Complex queries? → GraphQL │ │ └── Simple CRUD? → REST │ │ │ └─────────────────────────────────────────────────────────────────┘ ``` ## Quick Reference ### HTTP Methods | Method | Idempotent | Safe | Cacheable | Request Body | |--------|------------|------|-----------|--------------| | GET | Yes | Yes | Yes | No | | POST | No | No | No | Yes | | PUT | Yes | No | No | Yes | | PATCH | No* | No | No | Yes | | DELETE | Yes | No | No | Optional | ### Common Status Codes | Code | Name | Usage | |------|------|-------| | 200 | OK | Successful GET, PUT, PATCH | | 201 | Created | Successful POST (resource created) | | 204 | No Content | Successful DELETE | | 400 | Bad Request | Invalid syntax, validation error | | 401 | Unauthorized | Missing/invalid authentication | | 403 | Forbidden | Valid auth, no permission | | 404 | Not Found | Resource doesn't exist | | 409 | Conflict | Resource conflict | | 422 | Unprocessable | Semantic errors | | 429 | Too Many Requests | Rate limited | | 500 | Internal Error | Server error | ## Skills Index ### REST | Skill | Description | |-------|-------------| | [rest-principles](rest/rest-principles.md) | Core REST constraints and design | | [resource-naming](rest/resource-naming.md) | URI design and resource naming | | [http-methods](rest/http-methods.md) | HTTP verb semantics | | [status-codes](rest/status-codes.md) | HTTP status code usage | | [pagination](rest/pagination.md) | Pagination strategies | | [filtering-sorting](rest/filtering-sorting.md) | Query parameters design | | [versioning](rest/versioning.md) | API versioning approaches | ### GraphQL | Skill | Description | |-------|-------------| | [graphql-basics](graphql/graphql-basics.md) | GraphQL fundamentals | | [schema-design](graphql/schema-design.md) | Type system and schema | | [resolvers](graphql/resolvers.md) | Resolver patterns | | [mutations](graphql/mutations.md) | Write operations | | [subscriptions](graphql/subscriptions.md) | Real-time updates | ### gRPC | Skill | Description | |-------|-------------| | [grpc-basics](grpc/grpc-basics.md) | gRPC fundamentals | | [protobuf](grpc/protobuf.md) | Protocol Buffers | | [streaming](grpc/streaming.md) | Streaming patterns | ### Documentation | Skill | Description | |-------|-------------| | [openapi-swagger](documentation/openapi-swagger.md) | OpenAPI specification | | [api-documentation](documentation/api-documentation.md) | Documentation best practices | | [examples](documentation/examples.md) | Code examples and SDKs | ### Patterns | Skill | Description | |-------|-------------| | [request-response](patterns/request-response.md) | Request/response design | | [error-handling](patterns/error-handling.md) | Error handling patterns | | [authentication](patterns/authentication.md) | Auth patterns | | [rate-limiting](patterns/rate-limiting.md) | Rate limiting strategies | | [idempotency](patterns/idempotency.md) | Idempotent operations | ### Best Practices | Skill | Description | |-------|-------------| | [api-guidelines](best-practices/api-guidelines.md) | General API guidelines | | [backwards-compatibility](best-practices/backwards-compatibility.md) | Maintaining compatibility | | [api-evolution](best-practices/api-evolution.md) | Evolving APIs over time |