api-design

Use plural nouns for resource URLs like /v1/orders, map operations to HTTP methods (GET, POST, PUT, PATCH, DELETE), and return meaningful status codes such as 201 for creation with a Location header. Errors should follow RFC 7807 Problem Details format.

Choose REST for external-facing browser or mobile APIs with varied clients, gRPC for internal service-to-service communication that is performance-sensitive, and GraphQL for complex UI data needs aggregating many sources. Large systems often combine all three.

Prefer additive changes — add fields, never remove or repurpose them — so no version bump is needed. For genuinely breaking changes, use URI versioning like /v2/orders, support old versions through a deprecation window, and send Deprecation and Sunset headers.

Cursor pagination is best for large or volatile collections because it stays stable under insertions and performs efficiently. Offset/limit pagination works for small, stable collections where jumping to arbitrary pages matters. Always include a next_cursor in responses.

POST is not idempotent, so network retries can execute the operation twice. Support an Idempotency-Key header and store the key-to-response mapping server-side, returning the original response when the same key repeats instead of reprocessing.

Use action endpoints like POST /v1/orders/{id}/cancel when an operation does not map cleanly to CRUD and the action style communicates intent more clearly than a PATCH with a status field. Keep them rare and document the deviation.