--- frontmattername: api-design
description: API design principles for REST, GraphQL, and gRPC
category: skill
allowed-tools: Read, Write, Glob, Grep, Bash
user-invocable: true
context: inject
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
GraphQL
gRPC
Documentation
Patterns
Best Practices