api-design

Design HTTP or GraphQL API contracts with endpoints, methods, and error models.

12|1|Updated May 29, 2026

Search Tags:#versioning #rest #graphql #http #error-handling #pagination #api-design

Ready to run

npx skills add https://github.com/qdzsh/gsd-revamp --skill api-design-qdzsh

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: api-design
Source: https://github.com/qdzsh/gsd-revamp/tree/main/src/resources/skills/api-design
Command: npx skills add https://github.com/qdzsh/gsd-revamp --skill api-design-qdzsh

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Design contracts for HTTP/GraphQL APIs that are predictable, evolvable, and honest, enabling long-term client compatibility and easier maintenance.

Core Features & Use Cases

Define endpoints and operations with clear URL/operation naming, methods, request/response shapes, error shapes, and auth models.
Establish pagination, versioning, and status-code semantics that survive internal refactors.
Use cases: designing a new public API, redesigning an internal boundary between services, or performing a PR-level API review to ensure correctness and safety.

Quick Start

Design and document a concrete HTTP/GraphQL API sketch for a new service, including endpoints, methods, payloads, and error handling.

Frequently Asked Questions about api-design

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

FAQPage Schema

How do I design REST API contracts that remain evolvable without breaking existing clients?▼

Designing robust HTTP APIs involves specifying endpoint names, HTTP verbs, request/response shapes, and error models. Establishing pagination and versioning semantics ensures long-term client compatibility and predictable semantics during internal refactors.

What is the best way to structure HTTP error handling and pagination in a new public API?▼

Structuring HTTP error handling and pagination requires defining consistent error models and pagination semantics within the API contract. This approach delivers predictable, honest responses that survive internal service boundary refactors.

How do I review a pull request introducing new HTTP handlers for API correctness?▼

Reviewing a pull request for API correctness involves checking HTTP handlers against the API contract for proper endpoint naming, status-code semantics, error shapes, and authentication models to ensure predictable and safe integration.

Does this approach work for both GraphQL and REST API endpoint design?▼

Yes, this approach works for both GraphQL and REST API endpoint design. It shapes API contracts by specifying GraphQL operations or REST HTTP verbs, request/response shapes, and authentication models, requiring accompanying OpenAPI or SDL documentation.

When do I need to redesign an internal service boundary for API versioning?▼

You need to redesign an internal service boundary for API versioning when internal refactors threaten existing client compatibility. Establishing versioning and status-code semantics ensures the API boundary remains evolvable and honest for callers.