majiayu000/spellbook / skills/api-design
api-design
VerifiedREST/GraphQL/gRPC API design best practices. Use when designing APIs, defining contracts, handling versioning. Covers OpenAPI 3.2, GraphQL Federation, gRPC streaming.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 8.3 KB |
| reference/comparison.md | markdown | 6.1 KB |
| reference/graphql.md | markdown | 6.2 KB |
| reference/grpc.md | markdown | 7.4 KB |
| reference/rest.md | markdown | 5.3 KB |
| templates/graphql/schema.graphql | other | 4.5 KB |
| templates/grpc/service.proto | other | 6.0 KB |
| templates/openapi/openapi.yaml | config | 8.3 KB |
reference/comparison.md
View on GitHub# API Style Comparison
## Quick Decision Matrix
| Factor | REST | GraphQL | gRPC |
|--------|------|---------|------|
| Learning curve | Low | Medium | High |
| Browser support | Native | Native | Needs proxy |
| Tooling maturity | Excellent | Good | Good |
| Caching | HTTP native | Complex | Manual |
| File upload | Native | Complex | Native |
| Streaming | Limited | Subscriptions | Excellent |
| Type safety | Optional | Strong | Strong |
| Code generation | Optional | Common | Required |
| Performance | Good | Good | Excellent |
---
## Decision Tree
```
Start
│
├─ Public API for external developers?
│ └─ Yes → REST (simplicity, docs, caching)
│
├─ Mobile/SPA with complex data needs?
│ └─ Yes → GraphQL (flexible queries, reduced requests)
│
├─ Internal microservices communication?
│ └─ Yes → gRPC (performance, type safety)
│
├─ Real-time bidirectional streaming?
│ └─ Yes → gRPC (native streaming)
│
├─ Browser-only with real-time updates?
│ └─ Yes → GraphQL Subscriptions
│
└─ Simple CRUD with standard patterns?
└─ Yes → REST (simplicity wins)
```
---
## Detailed Comparison
### Data Fetching
**REST**
```
# Multiple requests for related data
GET /users/123
GET /users/123/orders
GET /orders/456/items
# Or use query params (non-standard)
GET /users/123?include=orders,orders.items
```
**GraphQL**
```graphql
# Single request, exact data
query {
user(id: "123") {
name
orders {
id
items { name price }
}
}
}
```
**gRPC**
```protobuf
// Need to design API carefully
rpc GetUserWithOrders(GetUserRequest) returns (UserWithOrders);
// Or make multiple calls (fast due to binary protocol)
```
### Over/Under Fetching
| Problem | REST | GraphQL | gRPC |
|---------|------|---------|------|
| Over-fetching | Common | Solved | Depends on design |
| Under-fetching | Common | Solved | Depends on design |
| N+1 requests | Common | Solved (DataLoader) | Manual batching |
---
### Versioning
**REST**
```
/v1/users → /v2/users
# Clear but requires migration
```
**GraphQL**
```graphql
# Field deprecation
type User {
name: String @deprecated(reason: "Use displayName")
displayName: String
}
# Continuous evolution without versions
```
**gRPC**
```
package api.v1; → package api.v2;
# Similar to REST
```
---
### Error Handling
**REST**
```json
// HTTP status codes + body
// 404 Not Found
{
"type": "https://api.example.com/errors/not-found",
"title": "User not found",
"status": 404
}
```
**GraphQL**
```json
// Always 200, errors in response
{
"data": null,
"errors": [{
"message": "User not found",
"extensions": { "code": "NOT_FOUND" }
}]
}
```
**gRPC**
```
// Status codes with details
INVALID_ARGUMENT: email format invalid
WITH_DETAILS: BadRequest { field_violations: [...] }
```
---
### Caching
**REST**
```
# Native HTTP caching
Cache-Control: max-age=3600
ETag: "abc123"
# CDN-friendly
```
**GraphQL**
```
# Complex - all requests are POST to same endpoint
# Solutions:
# - Persisted queries (GET with query hash)
# - Application-level caching
# - CDN with query normalization
```
**gRPC**
```
# No built-in caching
# Manual implementation required
# Often combined with Redis/Memcached
```
---
### Real-Time Updates
**REST**
```
# Polling (inefficient)
while (true) {
GET /orders?since=timestamp
sleep(5s)
}
# Server-Sent Events (unidirectional)
GET /events
Content-Type: text/event-stream
```
**GraphQL**
```graphql
# Subscriptions
subscription {
orderUpdated(orderId: "123") {
status
updatedAt
}
}
```
**gRPC**
```protobuf
# Bidirectional streaming
rpc WatchOrders(stream WatchRequest) returns (stream Order);
```
---
### File Uploads
**REST**
```
POST /files
Content-Type: multipart/form-data
# Native, simple
```
**GraphQL**
```
# Not in spec, various implementations
# graphql-upload package
# Separate REST endpoint common
```
**gRPC**
```protobuf
// Client streaming
rpc UploadFile(stream FileChunk) returns (UploadResponse);
// Native, efficient for large files
```
---
## Hybrid Architectures
### REST + GraphQL
```
┌─────────────────────────────────────────┐
│ API Gateway │
├─────────────────┬───────────────────────┤
│ REST Endpoints │ GraphQL Endpoint │
│ /v1/auth │ /graphql │
│ /v1/webhooks │ │
│ /v1/files │ │
└─────────────────┴───────────────────────┘
Use REST for:
- Authentication endpoints
- Webhooks (simple payload)
- File uploads
- Health checks
Use GraphQL for:
- Complex data queries
- Frontend-driven development
```
### GraphQL + gRPC (BFF Pattern)
```
┌─────────────┐
│ Client │
└──────┬──────┘
│ GraphQL
┌──────▼──────┐
│ BFF │ ← GraphQL Gateway
└──────┬──────┘
│ gRPC
┌──────▼──────┐
│ Microservices│
└─────────────┘
BFF aggregates gRPC services
Exposes unified GraphQL API
Handles auth, rate limiting
```
---
## Performance Benchmarks
| Metric | REST (JSON) | GraphQL | gRPC (Protobuf) |
|--------|-------------|---------|-----------------|
| Payload size | 1x | ~1x | 0.3-0.5x |
| Parse time | 1x | 1x | 0.1-0.3x |
| Latency | 1x | ~1x | 0.5-0.7x |
| Throughput | 1x | ~1x | 2-3x |
*Note: Actual results vary by use case*
---
## When NOT to Use
### REST
- Complex, deeply nested data requirements
- Real-time bidirectional communication
- Strict type safety requirements
### GraphQL
- Simple CRUD with few entities
- Heavy caching requirements
- Team unfamiliar with GraphQL
- File upload heavy applications
### gRPC
- Browser-only applications
- Public APIs (unless with gateway)
- Team lacks protobuf experience
- Heavy debugging/inspection needed
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |