TickYouOff
Sign in
Back
🔌

API Design Checklist

Hard 20 items · 1 hour
testuser's avatar
testuser Published 4 weeks ago
Technical

This checklist helps teams design clear, reliable RESTful APIs by covering naming, status codes, versioning, auth, rate limiting, errors, and docs. It’s for backend engineers, API designers, and product owners building or reviewing public or internal APIs.

Progress
0 / 20
  1. Define API purpose and audience — Clarify goals, consumers, SLAs, and intended integrations.
  2. Design resource URLs using plural nouns — Use /users and /orders; avoid verbs in path names.
  3. Limit URL nesting and model relations with IDs — Keep nesting shallow; prefer /users/{id}/orders over deep paths.
  4. Use standard HTTP methods appropriately — Map CRUD to GET/POST/PUT/PATCH/DELETE with proper semantics.
  5. Return consistent HTTP status codes — Use 200/201/204/400/401/403/404/409/429/500 consistently.
  6. Design consistent error response format — Include machine-readable code, human message, and requestId.
  7. Specify a clear versioning strategy — Include version in URL or header and document migration paths.
  8. Choose and document authentication and authorization — Prefer OAuth2/JWT or API keys; define scopes and roles.
  9. Document token lifecycle and refresh flow — Explain expiration, refresh tokens, rotation, and revocation.
  10. Implement rate limiting and quota headers — Protect endpoints and expose remaining/limit/reset headers.
  11. Ensure idempotency for write operations — Support idempotency keys for POSTs to avoid duplicate side effects.
  12. Support pagination, filtering, and sorting — Document params and prefer cursor pagination for large datasets.
  13. Use content negotiation and standard media types — Respect Accept/Content-Type headers and return consistent JSON schemas.
  14. Provide comprehensive documentation and OpenAPI spec — Include examples, schemas, auth flows, and downloadable OpenAPI files.
  15. Publish changelog and deprecation policy — Announce breaking changes, provide timelines and migration guidance.
  16. Design caching and use appropriate cache headers — Leverage ETag, Cache-Control, and Vary headers for GET responses.
  17. Enable CORS and set secure response headers — Allow only required origins and add standard security headers.
  18. Add health, metrics, and request tracing endpoints — Expose /health, metrics, and propagate request IDs for tracing.
  19. Write tests for contracts, integration, and load — Include contract tests, integration flows, and performance baselines.
  20. Run security reviews and input validation checks — Validate inputs, sanitize outputs, and perform vulnerability scans.
Sign in to save
📝 My Notes