skills.rest
open-gsd
open-gsdOFFICIAL
Explore all skills by this author →
Website𝕏@opengsdGitHub

api-design

Design HTTP and GraphQL API contracts with endpoints, schemas, and versioning.

1.0k|92|Updated May 22, 2026
Search Tags:#design#versioning#api#rest#graphql#error-handling#pagination
One-click install
npx skills add https://github.com/open-gsd/gsd-pi --skill api-design-open-gsd
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: api-design
Source: https://github.com/open-gsd/gsd-pi/tree/main/src/resources/skills/api-design
Command: npx skills add https://github.com/open-gsd/gsd-pi --skill api-design-open-gsd

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Designing robust HTTP and GraphQL APIs is challenging; teams must craft contracts that evolve gracefully, enforce consistent behavior, and reduce misinterpretations across services and clients.

Core Features & Use Cases

  • Contract-driven API design: define endpoints, methods, request/response shapes, auth models, and error schemas to ensure consistent behavior.
  • Pagination, versioning, and error handling: establish scalable strategies that support client growth and safe deprecation.
  • Design review framework: provide a structured checklist to validate completeness, compatibility, and rollout plans during PRs or architecture reviews.

Quick Start

Outline an API for a new service by listing endpoints, methods, data shapes, auth, pagination, and error handling rules.

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 and GraphQL APIs with consistent contracts?▼

Design predictable REST and GraphQL APIs by defining endpoints, methods, request and response shapes, auth models, and error schemas. This enforces contract completeness and ensures consistent behavior across services and clients.

What is the best way to handle API versioning and pagination for scalable growth?▼

Establish scalable API versioning and pagination strategies to support client growth and safe deprecation. Defining these policies early reduces misinterpretations and ensures graceful evolution across HTTP and GraphQL boundaries.

How do I validate API design completeness during pull requests?▼

Validate API design completeness during pull requests using a structured review checklist. This framework checks endpoint compatibility, contract details, and rollout plans to ensure safe architecture reviews.

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

Yes, this approach works for both REST and GraphQL boundaries. It applies contract-driven design to shape predictable HTTP and GraphQL APIs, detailing methods, data shapes, and error handling across both protocols.

Why do I need a defined error schema for my API endpoints?▼

A defined error schema is needed to enforce consistent API behavior and reduce misinterpretations across clients. Structured error handling ensures predictable responses when services fail or reject invalid requests.

Related Skills

Explore More Software Engineering Skills→
mpadmarajmpadmaraj
2

create-rest-api

Create REST API endpoints with contract design, validation, and test scaffolding.

Community
Intermediate
belokonmbelokonm
8

api-designer

Design REST and GraphQL APIs and generate OpenAPI 3.1 specifications.

Community
Advanced
lookatitudelookatitude
6

backend-api-contract

Designs implementable API contracts for REST, GraphQL, or RPC services.

Community
Advanced
Thiago-Cruz-engThiago-Cruz-eng

api-design-principles

Apply REST and GraphQL design principles to API review checklists.

Community
Advanced