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/rest.md
View on GitHub# REST API Deep Dive
## Request/Response Design
### Content Negotiation
```
# Request
Accept: application/json
Content-Type: application/json
# Response
Content-Type: application/json; charset=utf-8
```
### Standard Headers
| Header | Purpose | Example |
|--------|---------|---------|
| Authorization | Auth token | `Bearer eyJ...` |
| Accept | Response format | `application/json` |
| Content-Type | Request body format | `application/json` |
| Idempotency-Key | Prevent duplicates | UUID |
| X-Request-ID | Request tracing | UUID |
| X-RateLimit-* | Rate limit info | See below |
---
## Advanced Patterns
### Filtering
```
# Simple equality
GET /users?status=active
# Multiple values (OR)
GET /users?status=active,pending
# Comparison operators
GET /orders?total[gte]=100&total[lt]=1000
GET /users?created_at[after]=2025-01-01
# Full-text search
GET /products?q=laptop
# Nested filtering
GET /orders?user.country=US
```
### Sorting
```
# Single field
GET /users?sort=created_at
# Descending
GET /users?sort=-created_at
# Multiple fields
GET /users?sort=-created_at,name
```
### Field Selection (Sparse Fieldsets)
```
# Only return specific fields
GET /users?fields=id,name,email
# Nested fields
GET /orders?fields=id,total,user.name
```
### Embedding Related Resources
```
# Include related resources
GET /orders?include=user,items
# Response
{
"data": {
"id": "order-123",
"total": 99.99,
"user": { "id": "user-456", "name": "John" },
"items": [...]
}
}
```
---
## Bulk Operations
### Batch Create
```
POST /users/batch
Content-Type: application/json
{
"users": [
{ "email": "a@test.com", "name": "User A" },
{ "email": "b@test.com", "name": "User B" }
]
}
// Response: 207 Multi-Status
{
"results": [
{ "status": 201, "data": { "id": "1", ... } },
{ "status": 409, "error": { "message": "Email exists" } }
]
}
```
### Batch Update
```
PATCH /users/batch
Content-Type: application/json
{
"updates": [
{ "id": "1", "status": "active" },
{ "id": "2", "status": "inactive" }
]
}
```
### Batch Delete
```
DELETE /users/batch
Content-Type: application/json
{
"ids": ["1", "2", "3"]
}
```
---
## Long-Running Operations
### Async Pattern
```
# Start operation
POST /reports/generate
Content-Type: application/json
{ "type": "annual", "year": 2024 }
# Response: 202 Accepted
{
"operationId": "op-123",
"status": "pending",
"statusUrl": "/operations/op-123"
}
# Poll for status
GET /operations/op-123
# Response (in progress)
{
"operationId": "op-123",
"status": "running",
"progress": 45
}
# Response (complete)
{
"operationId": "op-123",
"status": "completed",
"result": {
"downloadUrl": "/reports/op-123/download"
}
}
```
---
## HATEOAS (Hypermedia)
```json
{
"data": {
"id": "order-123",
"status": "pending",
"total": 99.99
},
"_links": {
"self": { "href": "/orders/order-123" },
"cancel": { "href": "/orders/order-123/cancel", "method": "POST" },
"pay": { "href": "/orders/order-123/pay", "method": "POST" },
"user": { "href": "/users/user-456" }
}
}
```
---
## Caching
### Cache Headers
```
# Response headers
Cache-Control: private, max-age=3600
ETag: "abc123"
Last-Modified: Wed, 01 Jan 2025 00:00:00 GMT
# Conditional request
If-None-Match: "abc123"
If-Modified-Since: Wed, 01 Jan 2025 00:00:00 GMT
# Response if unchanged
304 Not Modified
```
### Cache Strategies
| Resource Type | Strategy |
|---------------|----------|
| Static config | `max-age=86400` (24h) |
| User data | `private, max-age=300` (5m) |
| List queries | `max-age=60` (1m) |
| Mutations | `no-store` |
---
## Webhooks
### Registration
```
POST /webhooks
Content-Type: application/json
{
"url": "https://myapp.com/webhook",
"events": ["order.created", "order.updated"],
"secret": "whsec_..."
}
```
### Payload
```json
{
"id": "evt_123",
"type": "order.created",
"created": "2025-01-15T10:30:00Z",
"data": {
"object": {
"id": "order-456",
"total": 99.99
}
}
}
```
### Signature Verification
```typescript
function verifyWebhook(payload: string, signature: string, secret: string): boolean {
const expected = crypto
.createHmac('sha256', secret)
.update(payload)
.digest('hex');
return crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(`sha256=${expected}`)
);
}
```
---
## OpenAPI Best Practices
### Operation IDs
```yaml
paths:
/users:
get:
operationId: listUsers # camelCase, verb + noun
post:
operationId: createUser
/users/{id}:
get:
operationId: getUser
put:
operationId: updateUser
delete:
operationId: deleteUser
```
### Reusable Components
```yaml
components:
schemas:
User:
type: object
properties:
id:
type: string
format: uuid
email:
type: string
format: email
parameters:
limitParam:
name: limit
in: query
schema:
type: integer
minimum: 1
maximum: 100
default: 20
responses:
NotFound:
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
```
### Tags for Organization
```yaml
tags:
- name: Users
description: User management
- name: Orders
description: Order operations
paths:
/users:
get:
tags: [Users]
```
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 |