api-design

API Design

Approach every API as a product. The developer calling your API is your user. An API that is hard to understand, inconsistent, or unpredictable is a broken product — even if it technically works.

Design the API before writing a single line of implementation. An API is a contract. Changing it after clients depend on it is expensive. Getting it right upfront is cheap.

API Design Principles

• Spec first, implement second. Write the OpenAPI spec, GraphQL schema, or proto file before any implementation. The spec is the contract. Implementation details are irrelevant to the caller.
• Consistency is the most important quality. Every endpoint in an API should behave according to the same rules: same error format, same naming convention, same pagination pattern, same auth mechanism. Inconsistency forces callers to write special-case code for every endpoint.
• APIs are forever. Every field you add is a field you must support until you version or sunset the API. Every field you remove is a breaking change. Design with permanence in mind.
• Design for the caller, not the data model. Your database schema is an implementation detail. Your API shape should reflect what callers need, not what your ORM produces.
• Explicit over implicit. Undefined behaviour in an API becomes the behaviour callers depend on. Make every behaviour explicit: required vs optional fields, error codes, rate limits, pagination behaviour at the end of a list.
• Developer experience is a first-class requirement. An API that requires a PhD to understand will not be adopted. Good error messages, consistent naming, and accurate documentation are as important as correct behaviour.

Step 0: Ground the API Design

Before designing any endpoint, answer these questions:

1. Who is the caller? Internal service, third-party developer, mobile app, browser, CLI? Each has different needs (auth mechanism, response size, error verbosity).
2. What resources does the API expose? List the core domain entities the API manages.
3. What operations does each resource support? CRUD is not always the right decomposition — sometimes cancel, approve, publish are better verbs than generic CRUD.
4. What are the read/write patterns? High-read, low-write? Real-time? Bulk operations? Streaming? This determines the API style.
5. What are the latency and payload size constraints? A mobile API on a 3G connection has different constraints than a backend-to-backend integration.
6. What versioning strategy is needed from day one? If this API will have external consumers, versioning must be designed in before the first endpoint ships.