A good API is a promise you can keep for years. This is the map: the conventions, the protocols, and the details that make an API pleasant to use and safe to change.
API Design Best Practices — The Complete Guide
An API is a contract, and the hard part is that you have to keep it for years while everything behind it changes. Good design is what lets you evolve without breaking the clients who depend on you. This guide is the map: the conventions that make an API predictable, the protocols to choose between, and the operational details (versioning, pagination, limits) that decide whether integrating with you is a pleasure or a support ticket.
The one principle underneath all of it: design for the consumer, not the database. An API that mirrors your tables leaks your internals and traps you; an API that models the domain the client actually cares about stays stable while you refactor freely.
- REST is the default for public and web APIs: resource-oriented, cacheable, universally understood. The conventions that matter are in REST API best practices.
- gRPC wins for internal service-to-service calls that need speed and strict contracts. The trade-offs vs REST are in gRPC vs REST.
- GraphQL shines when clients need flexible, exact-shape queries over a graph of data. When it beats REST (and when it doesn't) is in GraphQL vs REST.
Most systems end up with more than one: REST or GraphQL at the edge, gRPC between services.
These are the details that generate support tickets when they're wrong:
- Versioning: how to change an API without breaking existing clients, in API versioning strategies.
- Pagination: never return an unbounded list; offset vs cursor and their trade-offs are in API pagination.
- Rate limiting: protect the API and communicate limits clearly, in API rate limiting.
- Security: authentication, authorization, and the OWASP API risks are in API security best practices.
- Use nouns for resources and HTTP methods for actions; return the right status codes (2xx/4xx/5xx meaningfully).
- Be consistent: naming, casing, date formats (ISO 8601), and error shapes should be identical everywhere.
- Return structured, actionable errors (a code, a message, a field) so clients can handle them programmatically.
- Validate input strictly and reject unknown fields; be conservative in what you accept.
- Make writes idempotent where possible (idempotency keys) so retries are safe.
- Document everything with an OpenAPI/schema spec that is the source of truth.
Every API decision is really about change over time: a stable contract, explicit versioning, bounded responses, and clear errors are what let you refactor the implementation freely while clients keep working. Design the contract first (the shape clients see), then build to it. When you must break something, version it and give clients a migration path rather than a surprise.
Model the domain the consumer cares about, not your schema. Default to REST for public APIs, reach for gRPC between services and GraphQL when clients need query flexibility, and treat versioning, pagination, rate limiting, and errors as first-class from day one. Publish an OpenAPI spec and keep it honest. Each linked guide goes deep on one decision; start from the protocol choice, then nail the contract details that keep integrations from turning into tickets.
