skills.rest
qdzsh
qdzshCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

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
One-click install
npx skills add https://github.com/qdzsh/gsd-revamp --skill api-design-qdzsh
Or copy as Structured Prompt for Agent▼
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.

Related Skills

Explore More Software Engineering Skills→
arvindbattulaarvindbattula

api-contracts

Define stable API contracts for REST endpoints and TypeScript interfaces before implementation.

Community
Advanced
ekremmkasapekremmkasap

openapi-spec-generation

Generate and validate OpenAPI 3.1 specifications from code and design-first specs.

Community
Advanced
CleanExpoCleanExpo
3

api-testing

Validate Next.js App Router API endpoints against Zod schemas and security checks.

Community
Advanced
GaryOcean428GaryOcean428

api-design-validation

Validate REST API endpoint naming, HTTP methods, and status codes.

Community
Intermediate