backend-api-design

Installation
SKILL.md

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 — camelCase for JS/TS, snake_case for 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.

Installs
1
Repository
noih/dev-skills
First Seen
Apr 29, 2026