api-design

Design HTTP/GraphQL APIs with versioning, pagination, and error shapes.

Updated May 25, 2026
One-click install
npx skills add https://github.com/cmetech/otto-cli --skill api-design-cmetech
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: api-design
Source: https://github.com/cmetech/otto-cli/tree/main/src/resources/skills/api-design
Command: npx skills add https://github.com/cmetech/otto-cli --skill api-design-cmetech

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Design or review HTTP/REST/GraphQL APIs to enforce versioning, pagination, robust error shapes, idempotency, and secure authentication, ensuring evolution without breaking existing clients.

Core Features & Use Cases

  • Comprehensive API contract design that covers endpoints, methods, request/response shapes, and error handling for REST and GraphQL.
  • Guidance on versioning strategy, pagination, and status codes to support long-term client compatibility.
  • Actionable review workflows for adding new endpoints or redesigning service boundaries across microservices.

Quick Start

Design a REST endpoint for listing users with pagination.

Frequently Asked Questions about api-design

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I design an HTTP API that evolves without breaking existing clients?

Design HTTP APIs with predictable, evolvable semantics by defining versioning strategies, pagination, and robust error shapes that survive internal changes. Specify endpoint names, methods, request/response shapes, auth models, and versioning stance upfront to prevent breaking clients.

What is the best way to version REST API endpoints?

Version REST API endpoints by establishing a clear versioning stance during contract design. Choose strategies that support long-term client compatibility while allowing service boundaries to evolve without breaking existing integrations.

How do I structure error responses for a GraphQL API?

Structure GraphQL API error shapes by specifying consistent error formats during schema design. Ensure robust error handling covers request/response shapes and auth models, allowing the API to survive external integrations and internal changes predictably.

Can I use this approach to review and redesign API contracts across microservices?

Yes, use actionable review workflows for adding new endpoints or redesigning service boundaries across microservices. The approach applies to reviewing API surfaces across REST and GraphQL, covering contracts, auth, and status codes.

When do I need to specify pagination and idempotency in API design?

Specify pagination and idempotency in API design when creating comprehensive API contracts for REST or GraphQL. Define these during endpoint or schema sketches to support long-term client compatibility and robust integrations.

Does API design work for both REST and GraphQL service contracts?

Yes, API design applies to both REST and GraphQL service contracts. It covers endpoint and schema sketches specifying operation names, methods, request and response shapes, error shapes, auth models, pagination, and versioning.