API Design Review

Review in this order. It is roughly the order of how expensive each mistake is to fix once a client depends on it.

1. The model

Get this wrong and nothing downstream saves you.

• Do the resources match how users think, or how the database is arranged? These are frequently not the same. The API is a contract with a client, not a view of your schema.
• Is the grain right? One call per screen is chatty. One call that returns everything is a coupling nobody can evolve.
• Are relationships expressed consistently? Nested paths, or ids and a second call. Pick one and hold it.

2. Naming

Permanent, and free to get right now.

• Consistent case, one convention, everywhere. Do not mix userId and user_id.
• Plural collections, singular members. /users, /users/{id}.
• No verbs in resource paths. The method is the verb.
• Names that will still be true later. email outlives emailAddress2.
• Booleans named for the positive: enabled, not disabled, and never notDisabled.

3. Errors

The most-skipped part of API design and the one clients complain about most.

• Every error has a stable machine-readable code, distinct from the HTTP status. Clients must not branch on the human-readable message.
• The message says what to do about it, not just what went wrong.
• Validation errors name the field. One error per bad field, not a sentence listing them.
• Status codes are used correctly: 400 malformed, 401 unauthenticated, 403 authenticated but not permitted, 404 absent, 409 conflicts with current state, 422 well-formed but semantically invalid, 429 rate limited with a Retry-After.
• No 200 with an error body. That breaks every generic client.
• Errors never leak internals. No stack traces, no SQL, no internal hostnames.

4. Collections

• Pagination exists from day one, even when the list is short today. Adding it later is a breaking change.
• Cursor-based, not offset-based, for anything that can change while a client pages.
• A documented maximum page size, enforced.
• Filtering and sorting are explicit and finite. An open query language is an API you can never change.
• The response envelope is consistent: items plus pagination metadata, the same shape on every collection.

5. Evolution

Decide now how this changes later.

• How is a breaking change delivered? Version in the path, in a header, or never. Whatever the answer, write it down before the first client integrates.
• Which fields are required? Every required field is permanent. Optional with a sensible default is nearly always the better call.
• Are enums closed? A client that switches exhaustively on your enum breaks when you add a value. Say in the docs whether values may be added.
• Additive changes must be safe. Clients ignore unknown fields, and you never repurpose an existing one.

6. Everything else that becomes permanent

• Timestamps: ISO 8601, UTC, with an offset. Never a bare local time, never epoch seconds where milliseconds might later be needed.
• Money: integer minor units plus a currency code. Never a float.
• Identifiers: opaque strings. A client should never parse one, and a numeric id encourages exactly that.
• Nullability: distinguish "absent" from "explicitly null" and document which you mean.
• Idempotency: any unsafe method a client may retry needs an idempotency key.
• Rate limits: documented, with headers a client can read before hitting them.

Reporting

Group findings by cost to fix later, not by severity today. Lead with anything that becomes permanent the moment a client integrates, because that is the only window to change it for free.