ecc-api-designlisted

<!-- Source: affaan-m/ECC (MIT) - re-imported 2026-09-09 - moved and renamed for this baseline, frontmatter `name` set to the directory name; body unchanged. Licence text: .claude/THIRD-PARTY-LICENSES.md --> # API Design Patterns Conventions and best practices for designing consistent, developer-friendly REST APIs. ## When to Activate - Designing new API endpoints - Reviewing existing API contracts - Adding pagination, filtering, or sorting - Implementing error handling for APIs - Planning API versioning strategy - Building public or partner-facing APIs ## Resource Design ### URL Structure ``` # Resources are nouns, plural, lowercase, kebab-case GET /api/v1/users GET /api/v1/users/:id POST /api/v1/users PUT /api/v1/users/:id PATCH /api/v1/users/:id DELETE /api/v1/users/:id # Sub-resources for relationships GET /api/v1/users/:id/orders POST /api/v1/users/:id/orders # Actions that don't map to CRUD (use verbs sparingly) POST /api/v1/orders/:id/cancel POST /api/v1/auth/login POST /api/v1/auth/refresh ``` ### Naming Rules ``` # GOOD /api/v1/team-members # kebab-case for multi-word resources /api/v1/orders?status=active # query params for filtering /api/v1/users/123/orders # nested resources for ownership # BAD /api/v1/getUsers # verb in URL /api/v1/user # singular (use plural) /api/v1/team_members # snake_case in URLs /api/v1/users/123/getOrders # verb in nested resource ``` ## HTTP Method