REST for simple, well-defined resource CRUD. GraphQL for complex data graphs where consumers need flexible queries. Start with REST unless you have a strong reason for GraphQL.

How should I handle partial updates?

Use PATCH with JSON Merge Patch for simple cases. For complex partial updates, consider JSON Patch or field masks.

Should I use UUIDs or auto-increment IDs?

UUIDs for public-facing IDs to prevent enumeration. Auto-increment for internal references where performance matters.

API Design Checklist

Design APIs that developers love with consistent naming, clear error responses, proper pagination, and sensible versioning from the start.

Checklist: API Design (engineering)

API design decisions are hard to change after consumers integrate. Getting the fundamentals right from the start — naming, error handling, pagination, authentication, and versioning — saves enormous refactoring effort later.

Checklist Items

Use consistent resource naming conventions [critical]: Use plural nouns for collections, kebab-case for multi-word resources, and logical nesting for relationships.
Define a standard error response format [critical]: Create a consistent error schema with code, message, and details fields across all endpoints.
Implement proper HTTP status codes [critical]: Use 2xx for success, 4xx for client errors, 5xx for server errors. Never return 200 with an error body.
Design pagination for list endpoints [important]: Use cursor-based pagination for large datasets. Include total count, next/previous links, and configurable page size.
Add request and response validation [important]: Validate all inputs against JSON schemas. Return descriptive 400 errors with field-level detail.
Plan versioning strategy [important]: Choose URL-path or header-based versioning. Document deprecation timelines and migration guides.
Design idempotent endpoints [important]: Make PUT and DELETE idempotent. Use idempotency keys for POST requests to prevent duplicate operations.
Write OpenAPI specification [recommended]: Document all endpoints with OpenAPI/Swagger spec for auto-generated docs and client SDKs.
Design filtering and sorting [recommended]: Support query parameter-based filtering and sorting with consistent syntax across all list endpoints.
Plan rate limiting headers [recommended]: Return X-RateLimit-Limit, X-RateLimit-Remaining, and Retry-After headers so consumers can self-throttle.

Common Mistakes

Inconsistent naming across endpoints: Establish naming conventions in a style guide and enforce them through code review and linting.
Using offset pagination for large datasets: Offset pagination degrades on large tables. Use cursor-based pagination for consistent performance.
No versioning from the start: Add /v1/ prefix from your first endpoint. Adding versioning later is a breaking change for all consumers.

Frequently Asked Questions

REST or GraphQL?: REST for simple, well-defined resource CRUD. GraphQL for complex data graphs where consumers need flexible queries. Start with REST unless you have a strong reason for GraphQL.
How should I handle partial updates?: Use PATCH with JSON Merge Patch for simple cases. For complex partial updates, consider JSON Patch or field masks.
Should I use UUIDs or auto-increment IDs?: UUIDs for public-facing IDs to prevent enumeration. Auto-increment for internal references where performance matters.