Fullstack Dev API Design

API Design Guidelines

Framework-agnostic API design guide covering REST, GraphQL, and gRPC with 50+ rules across 10 categories.

Quick Start Checklist

• Resource named as plural noun (/orders not /getOrders)
• URL in kebab-case, body fields in camelCase
• Correct HTTP method (GET=read, POST=create, PUT=replace, PATCH=partial, DELETE=remove)
• Correct status code (201 Created, 422 Validation, 404 Not Found)
• Error response follows RFC 9457 envelope
• Pagination on all list endpoints (default 20, max 100)
• Authentication via Bearer token in header
• Request ID in response header (X-Request-Id)
• Rate limit headers included
• Endpoint documented in OpenAPI spec

Code Example: Error Response (RFC 9457)

{
  "type": "https://api.example.com/errors/insufficient-funds",
  "title": "Insufficient Funds",
  "status": 422,
  "detail": "Account balance $10.00 is less than withdrawal $50.00.",
  "request_id": "req_7f3a8b2c",
  "errors": [
    { "field": "amount", "message": "Exceeds balance", "code": "INSUFFICIENT_BALANCE" }
  ]
}

Code Example: Cursor Pagination

{
  "data": [...],
  "pagination": { "next_cursor": "abc123", "has_more": true }
}

Common Pitfalls

• Verbs in URLs: Use HTTP methods, not /getUser or /createOrder
• 200 for errors: Always use correct 4xx/5xx status codes
• Deep nesting: Max 2 levels nesting, then flatten with query params
• Stack traces in production: Log internally, return safe error messages
• No pagination: Always paginate list endpoints

Verification Checklist

• Resources use plural nouns
• HTTP methods match semantics
• Status codes correct for each scenario
• Error format consistent (RFC 9457)
• Pagination implemented on list endpoints
• OpenAPI spec documented