Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Design & UI

awesome-api-design

Designs or reviews an HTTP API's shape before code: resources, versioning, pagination, idempotency, filtering. Use when asked to design an API or an endpoint.

Khasky · Static checks on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add khasky/awesome-agent-skills --skill awesome-api-design

About this skill


name: awesome-api-design description: "Designs or reviews an HTTP API's shape before code: resources, versioning, pagination, idempotency, filtering. Use when asked to design an API or an endpoint." license: MIT metadata: author: Khasky tags: ["api", "design", "rest", "versioning", "pagination"] documentation: "https://github.com/khasky/awesome-agent-skills/tree/main/skills/awesome-api-design"

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}), actions as state transitions on them (POST /orders/{id}/cancel when a pure verb is unavoidable — never /doCancelOrder). Nest at most one level deep; deeper hierarchies become query filters (/comments?post_id=…), because every nesting level hardcodes an ownership assumption into every client URL.
  3. Decide the evolution rules before v1 ships — additive changes (new optional field, new endpoint) go in place; anything breaking (remove/rename/retype a field, tighten validation) only ever creates a new version. Publish that taxonomy with the API so consumers know what is safe to ignore. Evolve by layering — a redesigned abstraction ships beside the old one and existing integrations keep working until their owners move; deprecation is announced with a sunset window, never enforced by an in-place change.
  4. Design list endpoints for growth — opaque cursor pagination (encode the (sort_key, id) position, return has_more + next_cursor in a list envelope) over offset, which skips and duplicates rows under concurrent writes and dies on deep pages. Filtering and sorting are an allowlist of named parameters over indexed fields, never a pass-through to the query layer.
  5. Make unsafe methods retry-safe — mutations accept an Idempotency-Key; same key + same body replays the stored response, same key + different body is 409. Without it, every client retry is a potential duplicate side effect. (Retry classification and the envelope format: awesome-error-standards.)
  6. Specify concurrency and partial updates — updates that can conflict get optimistic concurrency (ETag + If-Match, 409 with the current version on mismatch); PATCH semantics are declared (merge-patch vs replace), and an empty PATCH is rejected, not silently a no-op.
  7. Write the contract down as the source of truth — an OpenAPI/schema document that generates or validates the implementation, not prose that drifts from it. Ids are opaque and prefixed (ord_…), timestamps ISO 8601 UTC, money integer minor units with currency, enums closed with a documented default for unknown values on the consumer side.

Design review checklist

When reviewing an existing design, walk the same decisions as findings:

  • Naming and casing consistent across every endpoint; no mixed camelCase/snake_case payloads.
  • No verbs in resource paths except modeled state transitions; no RPC-style /getX endpoints beside REST resources.
  • Every list endpoint paginated from day one — retrofitting pagination is a breaking change.
  • Every mutation idempotent-by-key or documented as naturally idempotent.
  • Error responses reference one stable envelope (awesome-error-standards) — not per-endpoint improvisation.
  • Versioning and deprecation policy stated; no "we'll decide when we break something".
  • Webhooks the API sends are treated as public surface: signed, versioned, redeliverable — same contract discipline as endpoints.
  • Nothing in the response a client shouldn't see: internal ids, flags, or fields leaking through by serializer default.

Change review

When the input is a change to a shipped contract (a diff to a spec, schema, handler or payload), review the change, not the end state. Compatibility is never declared from the new schema alone: read the old and new shapes side by side, and the code on both sides of the wire. Walk four scenarios and record the result of each:

  • Old writer, new reader: a payload produced before the change reaches code after it.
  • New writer, old reader: a payload produced after the change reaches code that has not been updated yet (still-deployed servers, shipped mobile or SDK builds).
  • Rollback: the old code returns while values only the new code writes are already stored or in flight.
  • Payloads at rest: old-format messages in queues, cache entries, stored rows and files are read by new code, and new-format ones by old code after a rollback.

Search for consumers both ways, in every repository you can reach:

  • A client reads a field the server stopped sending, renamed or retyped. This breaks silently: no error, a missing or wrong va
Read the complete source ↗