api-design

Installation
SKILL.md

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

Installs
15
Repository
noih/dev-skills
First Seen
Apr 30, 2026