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

api-design

API contract design: resource naming, error model, versioning, pagination, backward compatibility, OpenAPI. A predictable interface that evolves without breaking consumers.

byerlikaya · Static checks on file

Installation

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

npx skills add byerlikaya/claude-starter-kit --skill api-design

About this skill


name: api-design description: | API contract design: resource naming, error model, versioning, pagination, backward compatibility, OpenAPI. A predictable interface that evolves without breaking consumers.

API Design

Trigger phrases: "api design", "api contract", "api versioning", "openapi", "swagger", "rest contract", "breaking api change", "response shape", "response format", "endpoint returns", "error format"

Goal: a contract the consumer can predict and that can evolve without breaking. Once published, a public API is a commitment; a breaking change is expensive. Stack-agnostic (REST as the baseline; GraphQL/gRPC follow similar principles).

Checklist

  • Resource names are consistent (plural nouns, a single kebab/camel style), resources not verbs
  • Correct HTTP semantics: GET (side-effect free) · POST · PUT/PATCH · DELETE; correct status code
  • A uniform error model: machine-readable code + human message + (if any) field details
  • A clear versioning strategy (URL /v1 or header); a breaking change means a new version
  • Pagination/filtering/sorting defined and consistent on large collections
  • Backward compatibility: adding a field is additive; removing a field or changing its meaning is breaking → version
  • Idempotency (for POST/payment-like cases) supported via a key when needed
  • The contract is documented in OpenAPI; example request/response present (coordinate with docs-writer)

How

  1. Model the resource — a noun not a verb: POST /orders (✓), POST /createOrder (✗).
  2. Status codes: 200/201/204 · 400 validation · 401/403 authorization · 404 · 409 conflict · 422 · 429 · 5xx. Use them meaningfully.
  3. Error contract — every error has the same shape:
    { "code": "ORDER_NOT_FOUND", "message": "Order not found", "details": [] }
    
    No stack trace / internal detail leakage (overlaps with security-scan).
  4. Versioning: additive changes in the same version; breaking (remove/rename a field / add a required field) → /v2.
  5. Collection: pagination (cursor or offset), filter/sort parameters; a consistent envelope.
  6. Write the contract — OpenAPI/schema; with examples. Wire the change to docs-writer, and if breaking to release/CHANGELOG.

Breaking vs additive

Additive (safe)Breaking (needs a version)
Add an optional field/endpointRemove / rename a field
A new optional parameterAdd a required parameter
A new enum value (if the consumer is tolerant)Change a type/meaning, change a status code

Invariant rules

  1. A public API is a commitment — a breaking change is not made silently; version + announcement.
  2. Consistency > local cleverness — a single naming/error/pagination pattern across the whole API.
  3. The error model is uniform and machine-readable.
  4. No internal detail leakage — a stack trace / DB error does not go to the consumer.
  5. The contract is documented — OpenAPI + example; at design time, not after the code.