API Design Checklist

20 items · Technical · Hard difficulty · 1 hour

Design clear, consistent REST APIs with this practical checklist.

• Define API purpose and audience

  Clarify goals, consumers, SLAs, and intended integrations.

• Design resource URLs using plural nouns

  Use /users and /orders; avoid verbs in path names.

• Limit URL nesting and model relations with IDs

  Keep nesting shallow; prefer /users/{id}/orders over deep paths.

• Use standard HTTP methods appropriately

  Map CRUD to GET/POST/PUT/PATCH/DELETE with proper semantics.

• Return consistent HTTP status codes

  Use 200/201/204/400/401/403/404/409/429/500 consistently.

• Design consistent error response format

  Include machine-readable code, human message, and requestId.

• Specify a clear versioning strategy

  Include version in URL or header and document migration paths.

• Choose and document authentication and authorization

  Prefer OAuth2/JWT or API keys; define scopes and roles.

• Document token lifecycle and refresh flow

  Explain expiration, refresh tokens, rotation, and revocation.

• Implement rate limiting and quota headers

  Protect endpoints and expose remaining/limit/reset headers.

• Ensure idempotency for write operations

  Support idempotency keys for POSTs to avoid duplicate side effects.

• Support pagination, filtering, and sorting

  Document params and prefer cursor pagination for large datasets.

• Use content negotiation and standard media types

  Respect Accept/Content-Type headers and return consistent JSON schemas.

• Provide comprehensive documentation and OpenAPI spec

  Include examples, schemas, auth flows, and downloadable OpenAPI files.

• Publish changelog and deprecation policy

  Announce breaking changes, provide timelines and migration guidance.

• Design caching and use appropriate cache headers

  Leverage ETag, Cache-Control, and Vary headers for GET responses.

• Enable CORS and set secure response headers

  Allow only required origins and add standard security headers.

• Add health, metrics, and request tracing endpoints

  Expose /health, metrics, and propagate request IDs for tracing.

• Write tests for contracts, integration, and load

  Include contract tests, integration flows, and performance baselines.

• Run security reviews and input validation checks

  Validate inputs, sanitize outputs, and perform vulnerability scans.

Printed from TickYouOff — the interactive version tracks your progress and can be shared with others.