backend-api-design
API Design Conventions
Naming Conventions
- URL paths: Plural nouns, kebab-case (
/user-profiles/:id/addresses). Use nouns for resources, verbs only for actions (/orders/:id/cancel). - JSON fields: Follow the project's language convention —
camelCasefor JS/TS,snake_casefor Rust/Go. Be consistent within a project. - Query parameters: Use kebab-case (
/api/v1/products?type=voucher&category=digital-points). Do NOT use camelCase, snake_case, or other conventions for query filter names — always kebab-case.
Consumer-Driven Design
Design APIs based on how consumers use the data. When page references are available (Figma, live URL via chrome-devtools MCP, or frontend source code), study the page structure first and let it guide your API shape. When no page reference is available, reason from the requirements about what data each use case needs.
Endpoint Granularity
List vs Detail separation: If the feature involves browsing items and viewing individual ones, split into list and detail endpoints. The list endpoint returns only the fields the list view needs (e.g., id, title, thumbnail, summary). The detail endpoint returns the full resource. Never return all detail fields in a list response.
Single purpose: Each endpoint should serve one clear purpose. Avoid god endpoints that accept many optional parameters and behave differently based on parameter combinations — split them into semantically distinct endpoints.
Performance-driven splitting: Don't mix cheap and expensive operations. If a list page shows aggregate stats (counts, sums) that are expensive to compute, expose them as a separate stats endpoint so the client can fetch them in parallel without blocking the list.