Skip to content
Kitbay
Skill

api-and-interface-design

MITUpdated on Nov 1, 2026115,373GitHub stars

A skill from Addy Osmani's agent-skills collection for designing stable APIs and interfaces, such as REST or GraphQL endpoints, module boundaries, type contracts and the boundary between frontend and backend.

What the skill teaches

A skill from Addy Osmani's agent-skills collection for designing stable APIs and interfaces, such as REST or GraphQL endpoints, module boundaries, type contracts and the boundary between frontend and backend. It reminds the agent that any observable behaviour becomes something callers depend on, asks for the contract before the implementation, one error format everywhere, validation only at the edges, additive changes over breaking ones and predictable naming, and explains how to handle idempotency keys safely. It includes REST and TypeScript patterns, a verification checklist and warning signs such as unpaginated lists or verbs in URLs. It has no scripts.

Capabilities

  • Design REST and GraphQL endpoints and type contracts
  • Keep API changes additive and errors consistent
  • Handle idempotency keys safely
  • Check an API against a design checklist