# API Design Patterns
Conventions and best practices for designing consistent, developer-friendly REST APIs.
When to Activate
- Designing new API endpoints
- Reviewing existing API contracts
- Adding pagination, filtering, or sorting
- Implementing error handling for APIs
- Planning API versioning strategy
- Building public or partner-facing APIs
Resource Design
URL Structure
``` # Resources are nouns, plural, lowercase, kebab-case GET /api/v1/users GET /api/v1/users/:id POST /api/v1/users PUT /api/v1/users/:id PATCH /api/v1/users/:id DELETE /api/v1/users/:id
# Sub-resources for relationships GET /api/v1/users/:id/orders POST /api/v1/users/:id/orders
# Actions that don't map to CRUD (use verbs sparingly) POST /api/v1/orders/:id/cancel POST /api/v1/auth/login POST /api/v1/auth/refresh ```
Naming Rules
``` # GOOD /api/v1/team-members # kebab-case for multi-word resources /api/v1/orders?status=active # query params for filtering /api/v1/users/123/orders # nested resources for ownership
# BAD /api/v1/getUsers # verb in URL /api/v1/user # singular (use plural) /api/v1/team_members # snake_case in URLs /api/v1/users/123/getOrders # verb in nested resource ```
HTTP Methods and Status Codes
Method Semantics
| Method | Idempotent | Safe | Use For | |--------|-----------|------|---------| | GET | Yes | Yes | Retrieve resources | | POST | No | No | Create resources, trigger actions | | PUT | Yes | No | Full replacement of a resource | | PATCH | No* | No | Partial update of a resource | | DELETE | Yes | No | Remove a resource |
*PATCH can be made idempotent with proper implementation
Status Code Reference
``` # Success 200 OK — GET, PUT, PATCH (with response body) 201 Created — POST (include Location header) 204 No Content — DELETE, PUT (no response body)
# Client Errors 400 Bad Request — Validation failure, malformed JSON 401 Unauthorized — Missing or invalid authentication 403 Forbidden — Authenticated but not authorized 404 Not Found — Resource doesn't exist 409 Conflict — Duplicate entry, state conflict 422 Unprocessable Entity — Semantically invalid (valid JSON, bad data) 429 Too Many Requests — Rate limit exceeded
# Server Errors 500 Internal Server Error — Unexpected failure (never expose details) 502 Bad Gateway — Upstream service failed 503 Service Unavailable — Temporary overload, include Retry-After ```
Common Mistakes
``` # BAD: 200 for everything { "status": 200, "success": false, "error": "Not found" }
# GOOD: Use HTTP status codes semantically HTTP/1.1 404 Not Found { "error": { "code": "not_found", "message": "User not found" } }
# BAD: 500 for validation errors # GOOD: 400 or 422 with field-level details
# BAD: 200 for created resources # GOOD: 201 with Location header HTTP/1.1 201 Created Location: /api/v1/users/abc-123 ```
Response Format
Success Response
```json { "data": { "id": "abc-123", "email": "alice@example.com", "name": "Alice", "created_at": "2025-01-15T10:30:00Z" } } ```
Collection Response (with Pagination)
```json { "data": [ { "id": "abc-123", "name": "Alice" }, { "id": "def-456", "name": "Bob" } ], "meta": { "total": 142, "page": 1, "per_page": 20, "total_pages": 8 }, "links": { "self": "/api/v1/users?page=1&per_page=20", "next": "/api/v1/users?page=2&per_page=20", "last": "/api/v1/users?page=8&per_page=20" } } ```
Error Response
```json { "error": { "code": "validation_error", "message": "Request validation failed", "details": [ { "field": "email", "message": "Must be a valid email address", "code": "invalid_format" }, { "field": "age", "message": "Must be between 0 and 150", "code": "out_of_range" } ] } } ```
Response Envelope Variants
```typescript // Option A: Envelope with data wrapper (recommended for public APIs) interface ApiResponse<T> { data: T; meta?: PaginationMeta; links?: PaginationLinks; }
interface ApiError { error: { code: string; message: string; details?: FieldError[]; }; }
// Option B: Flat response (simpler, common for internal APIs) // Success: just return the resource directly // Error: return error object // Distinguish by HTTP status code ```
Pagination
Offset-Based (Simple)
``` GET /api/v1/users?page=2&per_page=20
# Implementation SELECT * FROM users ORDER BY created_at DESC LIMIT 20 OFFSET 20; ```
**Pros:** Easy to implement, supports "jump to page N" **Cons:** Slow on large offsets (OFFSET 100000), inconsistent with concurrent inserts
Cursor-Based (Scalable)
``` GET /api/v1/users?cursor=eyJpZCI6MTIzfQ&limit=20
# Implementation SELECT * FROM users WHERE id > :cursor_id ORDER BY id ASC LIMIT 21; -- fetch one extra to determine has_next ```
```json { "data": [...], "meta": { "has_next": true, "next_cursor": "eyJpZCI6MTQzfQ" } } ```
**Pros:** Consistent performance regardless of position, stable with concurrent inserts **Cons:** Cannot jump to arbitrary page, cursor is opaque
When to Use Which
| Use Case | Pagination Type | |----------|----------------| | Admin dashboards, small datasets (<10K) | Offset | | Infinite scroll, feeds, large datasets | Cursor | | Public APIs | Cursor (default) with offset (optional) | | Search results | Offset (users expect page numbers) |
Filtering, Sorting, and Search
Filtering
``` # Simple equality GET /api/v1/orders?status=active&customer_id=abc-123
# Comparison operators (use bracket notation) GET /api/v1/products?price[gte]=10&price[lte]=100 GET /api/v1/orders?created_at[after]=2025-01-01
# Multiple values (comma-separated) GET /api/v1/products?category=electronics,clothing
# Nested fields (dot notation) GET /api/v1/orders?customer.country=US ```
Sorting
``` # Single field (prefix - for descending) GET /api/v1/products?sort=-created_at
# Multiple fields (comma-separated) GET /api/v1/products?sort=-featured,price,-created_at ```
Full-Text Search
``` # Search query parameter GET /api/v1/products?q=wireless+headphones
# Field-specific search GET /api/v1/users?email=alice ```
Sparse Fieldsets
``` # Return only specified fields (reduces payload) GET /api/v1/users?fields=id,name,email GET /api/v1/orders?fields=id,total,status&include=customer.name ```
Authentication and Authorization
Token-Based Auth
``` # Bearer token in Authorization header GET /api/v1/users Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
# API key (for server-to-server) GET /api/v1/data X-API-Key: sk_live_abc123 ```
Authorization Patterns
```typescript // Resource-level: check ownership app.get("/api/v1/orders/:id", async (req, res) => { const order = await Order.findById(req.params.id); if (!order) return res.status(404).json({ error: { code: "not_found" } }); if (order.userId !== req.user.id) return res.status(403).json({ error: { code: "forbidden" } }); return res.json({ data: order }); });
// Role-based: check permissions app.delete("/api/v1/users/:id", requireRole("admin"), async (req, res) => { await User.delete(req.params.id); return res.status(204).send(); }); ```
Rate Limiting
Headers
``` HTTP/1.1 200 OK X-RateLimit-Limit: 100 X-RateLimit-Remaining: 95 X-RateLimit-Reset: 1640000000
# When exceeded HTTP/1.1 429 Too Many Requests Retry-After: 60 { "error": { "code": "rate_limit_exceeded", "message": "Rate limit exceeded. Try again in 60 seconds." } } ```
Rate Limit Tiers
| Tier | Limit | Window | Use Case | |------|-------|--------|----------| | Anonymous | 30/min | Per IP | Public endpoints | | Authenticated | 100/min | Per user | Standard API access | | Premium | 1000/min | Per API key | Paid API plans | | Internal | 10000/min | Per service | Service-to-service |
Versioning
URL Path Versioning (Recommended)
``` /api/v1/users /api/v2/users ```
**Pros:** Explicit, easy to route, cacheable **Cons:** URL changes between versions
Header Versioning
``` GET /api/users Accept: application/vnd.myapp.v2+json ```
**Pros:** Clean URLs **Cons:** Harder to test, easy to forget
Versioning Strategy
``` 1. Start with /api/v1/ — don't version until you need to 2. Maintain at most 2 active versions (current + previous) 3. Deprecation timeline: - Announce deprecation (6 months notice for public APIs) - Add Sunset header: Sunset: Sat, 01 Jan 2026 00:00:00 GMT - Return 410 Gone after sunset date 4. Non-breaking changes don't need a new version: - Adding new fields to responses - Adding new optional query parameters - Adding new endpoints 5. Breaking changes require a new version: - Removing or renaming fields - Changing field types - Changing URL structure - Changing authentication method ```
Implementation Patterns
TypeScript (Next.js API Route)
```typescript import { z } from "zod"; import { NextRequest, NextResponse } from "next/server";
const createUserSchema = z.object({ email: z.string().email(), name: z.string().min(1).max(100), });
export async function POST(req: NextRequest) { const body = await req.json(); const parsed = createUserSchema.safeParse(body);
if (!parsed.success) { return NextResponse.json({ error: { code: "validation_error", message: "Request validation failed", details: parsed.error.issues.map(i => ({ field: i.path.join("."), message: i.message, code: i.code, })), }, }, { status: 422 }); }
const user = await createUser(parsed.data);
return NextResponse.json( { data: user }, { status: 201, headers: { Location: `/api/v1/users/${user.id}` }, }, ); } ```
Python (Django REST Framework)
```python from rest_framework import serializers, viewsets, status from rest_framework.response import Response
class CreateUserSerializer(serializers.Serializer): email = serializers.EmailField() name = serializers.CharField(max_length=100)
class UserSerializer(serializers.ModelSerializer): class Meta: model = User fields = ["id", "email", "name", "created_at"]
class UserViewSet(viewsets.ModelViewSet): serializer_class = UserSerializer permission_classes = [IsAuthenticated]
def get_serializer_class(self): if self.action == "create": return CreateUserSerializer return UserSerializer
def create(self, request): serializer = CreateUserSerializer(data=request.data) serializer.is_valid(raise_exception=True) user = UserService.create(**serializer.validated_data) return Response( {"data": UserSerializer(user).data}, status=status.HTTP_201_CREATED, headers={"Location": f"/api/v1/users/{user.id}"}, ) ```
Go (net/http)
```go func (h *UserHandler) CreateUser(w http.ResponseWriter, r *http.Request) { var req CreateUserRequest if err := json.NewDecoder(r.Body).Decode(&req); err != nil { writeError(w, http.StatusBadRequest, "invalid_json", "Invalid request body") return }
if err := req.Validate(); err != nil { writeError(w, http.StatusUnprocessableEntity, "validation_error", err.Error()) return }
user, err := h.service.Create(r.Context(), req) if err != nil { switch { case errors.Is(err, domain.ErrEmailTaken): writeError(w, http.StatusConflict, "email_taken", "Email already registered") default: writeError(w, http.StatusInternalServerError, "internal_error", "Internal error") } return }
w.Header().Set("Location", fmt.Sprintf("/api/v1/users/%s", user.ID)) writeJSON(w, http.StatusCreated, map[string]any{"data": user}) } ```
API Design Checklist
Before shipping a new endpoint:
- [ ] Resource URL follows naming conventions (plural, kebab-case, no verbs)
- [ ] Correct HTTP method used (GET for reads, POST for creates, etc.)
- [ ] Appropriate status codes returned (not 200 for everything)
- [ ] Input validated with schema (Zod, Pydantic, Bean Validation)
- [ ] Error responses follow standard format with codes and messages
- [ ] Pagination implemented for list endpoints (cursor or offset)
- [ ] Authentication required (or explicitly marked as public)
- [ ] Authorization checked (user can only access their own resources)
- [ ] Rate limiting configured
- [ ] Response does not leak internal details (stack traces, SQL errors)
- [ ] Consistent naming with existing endpoints (camelCase vs snake_case)
- [ ] Documented (OpenAPI/Swagger spec updated)