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 |
Core REST constraints and design |
| resource-naming |
URI design and resource naming |
| http-methods |
HTTP verb semantics |
| status-codes |
HTTP status code usage |
| pagination |
Pagination strategies |
| filtering-sorting |
Query parameters design |
| versioning |
API versioning approaches |
GraphQL
| Skill |
Description |
| graphql-basics |
GraphQL fundamentals |
| schema-design |
Type system and schema |
| resolvers |
Resolver patterns |
| mutations |
Write operations |
| subscriptions |
Real-time updates |
gRPC
| Skill |
Description |
| grpc-basics |
gRPC fundamentals |
| protobuf |
Protocol Buffers |
| streaming |
Streaming patterns |
Documentation
| Skill |
Description |
| openapi-swagger |
OpenAPI specification |
| api-documentation |
Documentation best practices |
| examples |
Code examples and SDKs |
Patterns
| Skill |
Description |
| request-response |
Request/response design |
| error-handling |
Error handling patterns |
| authentication |
Auth patterns |
| rate-limiting |
Rate limiting strategies |
| idempotency |
Idempotent operations |
Best Practices
| Skill |
Description |
| api-guidelines |
General API guidelines |
| backwards-compatibility |
Maintaining compatibility |
| api-evolution |
Evolving APIs over time |
Fujigo-Software