api-design-standards

API Design Standards

An API is a promise to callers you don't control and usually can't see. Adding to that promise is free; changing or removing part of it breaks someone who already depended on it. Every API change is classified against that promise (additive or breaking) before it ships, not discovered after a caller files a bug.

Phase 1: Resource and URL conventions

• URLs name resources (nouns), never actions (verbs): POST /orders, not POST /createOrder. The HTTP method carries the verb.
• Collections are plural (/orders), a specific member is the collection plus an identifier (/orders/{id}), and nesting reflects real ownership (/orders/{id}/items), not an arbitrary path someone found convenient.
• HTTP methods map to a fixed meaning, and only that meaning: GET (read, no side effects, safe to retry and cache), POST (create, or a non-idempotent action), PUT (full replace, idempotent, calling it twice with the same body leaves the same state), PATCH (partial update), DELETE (remove, idempotent).
• Status codes communicate outcome precisely: 2xx success (201 for created with a Location header, 204 for success with no body), 4xx the caller's fault (400 malformed request, 401 unauthenticated, 403 authenticated but not authorized, 404 not found, 409 conflict, 422 semantically invalid), 5xx the server's fault. Returning 200 with an error payload embedded in the body hides the failure from every generic HTTP-aware tool (retries, caches, monitoring).

Phase 2: Versioning strategy

Pick one signal and use it consistently across the whole API; mixing strategies forces every client to handle more than one: