Once other systems depend on your API, every change carries a cost for someone else. Good design up front makes future changes additive instead of breaking.
Model resources, not screens
Design endpoints around stable business concepts — orders, customers, invoices — rather than around what one particular page of your frontend needs today.
Be consistent everywhere
- One naming style for fields across all endpoints
- The same pagination pattern on every list
- One error format with a machine-readable code and a human-readable message
- Consistent date formats, ideally ISO 8601 in UTC
Plan for change
Additive changes are safe
Adding optional fields or new endpoints rarely breaks clients. Removing or renaming fields, or changing their meaning, does.
Version deliberately
When a breaking change is unavoidable, introduce a new version, run both for a clear deprecation period and communicate the timeline early.
Make operations safe to retry
Networks fail. Support idempotency keys on create operations so a client can retry a request without creating duplicates.
Document with examples
A machine-readable specification (such as OpenAPI) plus realistic request and response examples lets integrators succeed without contacting your team.
Common questions
REST or GraphQL?
REST is simple, cache-friendly and widely understood. GraphQL helps when many clients need different shapes of the same data. Choose based on your consumers, not on trends.
How should errors look?
Use the correct HTTP status code, plus a body containing a stable error code, a readable message and, where helpful, the field that caused the problem.
- API
- REST
- Integration
