api-design
API Design Conventions
These are personal defaults for new contracts. Preserve established public contracts and project conventions; do not rename fields or change formats merely to match these preferences. Use consumer needs and compatibility to resolve exceptions.
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: Prefer kebab-case for a new contract (
/api/v1/products?type=voucher&category=digital-points); preserve existing query parameter names and conventions
Consumer-Driven Design
Design APIs based on how consumers use the data. When page references are available (Figma, a live URL inspected with whatever browser tooling is available, 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: Separate list and detail shapes when their data needs or costs differ. Keep list payloads focused on the consumer's needs; a small resource may legitimately use the same shape for both without artificial splitting.
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.