api-design

name api-design description REST API design patterns including resource naming, status codes, pagination, filtering, error responses, versioning, and rate limiting for production APIs. Use when designing or reviewing REST endpoints, resource names, status codes, pagination, or versioning. metadata {"origin":"ECC"} 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 { "data" : { "id" : "abc-123" , "email" : "alice@example.com" , "name" : "Alice" , "created_at" : "2025-01-15T10:30:00Z" } } Collection Response (with Pagination) { "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 { "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 // 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 { "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 // 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) 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) 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 ):