api-designlisted

# API Design Design choices for HTTP APIs (REST-style and GraphQL). The goal is an API that is consistent, predictable, and easy to evolve without breaking callers. Reference: [Google API Design Guide](https://cloud.google.com/apis/design), [JSON:API](https://jsonapi.org/), [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) (Problem Details for HTTP APIs). --- ## Resource naming (REST) Use nouns, not verbs. Collections are plural. ``` GET /users → list users POST /users → create a user GET /users/{id} → get one user PATCH /users/{id} → partial update PUT /users/{id} → full replace DELETE /users/{id} → delete GET /users/{id}/posts → posts belonging to a user POST /users/{id}/posts → create a post for a user ``` Actions that don't map cleanly to CRUD go on a sub-resource with a verb: ``` POST /users/{id}/activate POST /payments/{id}/refund ``` **Naming rules:** - `kebab-case` for multi-word path segments (`/user-profiles`, not `/userProfiles` or `/user_profiles`) - `camelCase` for JSON field names (consistent with most JS/TS clients) - IDs in path, filters/pagination in query string --- ## HTTP status codes — use them correctly | Code | Meaning | Use for | |---|---|---| | 200 | OK | Successful GET, PATCH, PUT | | 201 | Created | Successful POST that creates a resource | | 204 | No Content | Successful DELETE or action with no response body | | 400 | Bad Request | Client sent invalid