awesome-api-designlisted

Designs or reviews the shape of an HTTP API before code exists — resources, versioning, pagination, idempotency, filtering, and where the error contract plugs in. Use when asked to design or review an API, decide versioning or pagination, add an endpoint at the design stage, 'спроектируй API', or when awesome-design-doc needs the contract detailed. Do not use for the error envelope itself (awesome-error-standards), vulnerability review of handlers (awesome-security-audit), or auditing an implemented architecture (awesome-architecture-audit).
khasky/awesome-agent-skills · ★ 8 · Code & Development · score 78

Install: claude install-skill khasky/awesome-agent-skills

# API Design Shape an HTTP API so its consumers can build against it for years without a breaking surprise. The contract is the product: URLs, methods, payloads, errors, and evolution rules are decided here, deliberately — everything left implicit becomes an accidental contract the first client depends on. ## When to Activate - "Design the API for X", "review this API design / OpenAPI spec", "how should we version / paginate / handle retries". - A design doc needs its API section made concrete (awesome-design-doc hands off here). - A new endpoint is being added to an existing API and must match its conventions. Do not activate to define the error envelope's fields or retry classification (awesome-error-standards owns that contract) or to audit implemented handlers for vulnerabilities (awesome-security-audit). ## Work Process 1. Inventory the incumbent conventions and the project's own words — an existing API's casing, id format, pagination style, and envelope win over any guideline here: consistency within one API beats global best practice. Only a new API starts from the defaults below. Read the recorded decisions (existing ADRs) and the project's glossary (`CONTEXT.md`, a domain doc, or the terms its code and tests already use) before naming a single resource: a path is a public, long-lived name, and one that renames a concept the codebase already has costs every reader a translation. 2. Model resources, not procedures — nouns with identity and lifecycle (`/orders/{id