common-api-design

# Common API Design Standards ## **Priority: P1 (OPERATIONAL)** Consistent, predictable API contracts reduce integration friction and prevent breaking changes from reaching consumers. ## 🔧 HTTP Verb Semantics - `GET` read-only, idempotent — never mutates state. - `POST` create or trigger; `PUT` full replace; `PATCH` partial update; `DELETE` remove. - Non-CRUD actions as sub-resources: `POST /orders/:id/cancel`. ## 📡 Status Code Correctness - `200` success; `201` created (add `Location` header); `204` no body. - `400` validation (with `details[]`); `401` unauthenticated; `403` unauthorized; `404` not found. - `409` conflict; `422` business rule violation; `429` rate limit (add `Retry-After`); `500` unhandled. ## 📦 URL Design Rules - **Lowercase, kebab-case**: `/user-profiles`, not `/UserProfiles` or `/user_profiles`. - **Plural nouns**: `/orders`, `/products`. Not `/order`, `/getProducts`. - **No verbs in paths** (except action sub-resources): `/orders/:id/cancel` ✅, `/cancelOrder` ❌. - **Hierarchy**: Use nesting only up to 2 levels: `/users/:id/orders` ✅, `/users/:id/orders/:orderId/items/:itemId` ❌. ## 🔢 API Versioning - **Strategy**: URL path versioning is the default: `/v1/users`, `/v2/users`. - **Header versioning** (`Api-Version: 2`) is acceptable for internal APIs. - Never mix versions in the same controller — each version gets its own route module. - Support previous major version for minimum 6 months after a new one is released. - Deprecation: Add `Depre...