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) | Gr