skills.rest
vh2224
vh2224COMMUNITY
Explore all skills by this author →
GitHub

api-design

Design and review HTTP and GraphQL APIs with status codes, contracts, pagination, auth, and versioning.

1|Updated Jul 13, 2026
Search Tags:#versioning#error handling#api design#rest#graphql#pagination#auth
One-click install
npx skills add https://github.com/vh2224/forge-executor --skill api-design-vh2224
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: api-design
Source: https://github.com/vh2224/forge-executor/tree/main/src/resources/skills/api-design
Command: npx skills add https://github.com/vh2224/forge-executor --skill api-design-vh2224

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This Skill helps you design or review HTTP and GraphQL APIs so they are predictable, evolvable, and honest about errors, status codes, and compatibility.

Core Features & Use Cases

  • Endpoint and schema design: Define REST resources, GraphQL operations, request/response shapes, and naming conventions for new or changing APIs.
  • Contract quality review: Check versioning strategy, pagination, auth, idempotency, concurrency, and error handling for existing API changes.
  • Production-ready semantics: Ensure list endpoints paginate, errors are machine-readable, breaking changes are handled safely, and documentation reflects the contract.
  • Use case: A team adding a new public endpoint can use this Skill to choose the right method, status codes, pagination model, and backward-compatible evolution plan.

Quick Start

Ask for an API design or review with the caller type, auth model, versioning stance, and the endpoint or schema you want assessed.

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 correct status codes and pagination?▼

To design REST and GraphQL APIs, define predictable request and response contracts, apply correct HTTP status codes, implement pagination for list endpoints, and ensure machine-readable errors. This approach creates API surfaces callers can trust.

What is the best way to handle API versioning and backward-compatible evolution?▼

The best way to handle API versioning is to establish a clear versioning stance and apply backward-compatible evolution plans for schema changes. This ensures breaking changes are managed safely without disrupting existing API callers.

How do I review an existing API contract for idempotency and concurrency control?▼

Review an existing API contract by checking its idempotency keys, concurrency control mechanisms, and error handling formats. This validates that the API maintains predictable semantics during concurrent operations and cross-service communication.

Can I use this approach for both internal cross-service APIs and public endpoints?▼

Yes, this API design approach applies to public, internal, and cross-service API surfaces. It ensures consistent endpoint design, auth models, and documentation whether you are adding new endpoints or modifying existing schemas.

Why do my API errors need to be machine-readable?▼

API errors need to be machine-readable so calling systems can programmatically handle failures and retry logic correctly. Predictable error semantics are essential for maintaining reliable integrations across public and internal API surfaces.

Related Skills

Explore More Software Engineering Skills→
tranhieutttranhieutt
70

api-design

Review REST and GraphQL API contracts for naming, schema, auth, and versioning issues.

Community
Intermediate
686f6c61686f6c61
105

api-docs

Generate API documentation with HTTP methods, routes, parameters, and schemas.

Community
Intermediate
cmetechcmetech

api-design

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

Community
Advanced
bbara04bbara04

designing-apis

Guide REST and GraphQL API contract design with endpoint patterns and schema structure.

Community
Intermediate