An API is a contract with the outside world. Once consumers depend on it, every change is either a breaking change or a carefully managed evolution. The best API design minimizes the number of breaking changes you ever have to make.
Good API design is about consistency, clarity and forgiveness: consistent patterns make endpoints predictable, clarity makes intent obvious, and forgiveness means errors are easy to handle.
Naming and structure
Use nouns for resources, verbs only for actions that are not natural CRUD. Keep a consistent shape across the whole API so clients never guess.
- /orders, /orders/:id, /orders/:id/items.
- POST to create, GET to read, PATCH for partial updates.
- Prefer REST-style resources unless real-time needs demand otherwise.
- Version via the URL or a content-type header, but pick one.
Errors that help, not confuse
A good error response contains an HTTP status, a machine-readable code, a human message and a way to find help. Include validation details as structured fields, not formatted strings.
If an error response requires reading the docs to understand, the API is leaking its implementation details into the contract.
Pagination and idempotency
Default to cursor-based pagination for large lists and always return a stable ordering. Use idempotency keys on payment and order endpoints so retries are safe — networks drop requests, and clients will retry.
{
"error": {
"code": "VALIDATION_ERROR",
"message": "The order total cannot be negative.",
"fields": [{ "field": "total", "reason": "must be >= 0" }],
"documentation": "https://docs.example.com/errors#VALIDATION_ERROR"
}
}API design FAQ
Should every endpoint be versioned?
No. Versioning is a mechanism of last resort. Prefer additive changes and deprecation periods. Version only when you must break existing behavior.
GraphQL or REST?
REST is simpler to cache, monitor and secure. GraphQL excels when clients need flexible, over-fetched data with minimal round trips. Choose based on client needs, not fashion.
