Common API Design Standards

Priority: P1 (HIGH)

🔧 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 default: /v1/users, /v2/users.
• Header versioning (Api-Version: 2) acceptable for internal APIs.
• Never mix versions in same controller, each version gets its own route module.
• Support prev major ≥ 6 months after new release.
• Deprecation: Deprecation: true + Sunset: <date> headers when version will be retired.

📄 Pagination

• Prefer cursor-based (cursor + limit) for large/live datasets; offset only for small static ones.
• Default limit: 20, max 100. Reject requests exceeding max.
• Response envelope: { data: [], pagination: { nextCursor, hasNextPage } }.

📝 OpenAPI Contract

• Generate from code annotations, not hand-written YAML.
• Every API needs OpenAPI 3.1 spec.
• Include: request/response schemas, error shapes, auth requirements, examples.
• Review spec in PR, breaking changes need version bump.

🔒 API Security Baseline