skills.rest
jvsandhu
jvsandhuCOMMUNITY
Explore all skills by this author →
GitHub

api_design

Designs RESTful and GraphQL APIs with OpenAPI specs, versioning, and contract testing workflows.

Updated Jan 14, 2026
Search Tags:#versioning#api design#openapi#rest#graphql#contract testing#spec-first
One-click install
npx skills add https://github.com/jvsandhu/agentic-skills --skill api-design-jvsandhu
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: api_design
Source: https://github.com/jvsandhu/agentic-skills/tree/main/skills/api_design
Command: npx skills add https://github.com/jvsandhu/agentic-skills --skill api-design-jvsandhu

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Teams often build APIs without a specification first, leading to inconsistent endpoints, mismatched types between code and docs, and breaking changes discovered too late. This Skill enforces a spec-first workflow so APIs are designed, mocked, and validated before implementation begins. ## Core Features & Use Cases - Spec-First Design: Draft OpenAPI 3.0 or GraphQL schemas before writing code, with endpoint naming conventions, status code guidance, and standard response formats. - Versioning & Error Standards: Apply URL-based versioning patterns and consistent error response structures (RFC 7807 style) across all endpoints. - Contract Testing & Docs: Verify implementation matches the spec with contract tests, then publish Swagger UI or Redoc documentation. - Use Case: When starting a new microservice, use this Skill to define the OpenAPI spec, generate a mock server for frontend teams, generate TypeScript types via codegen, and run contract tests to keep code and spec synchronized. ## Quick Start Design a versioned REST API for a users resource with an OpenAPI spec, standard error responses, and a mock server for frontend testing.

Frequently Asked Questions about api_design

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

FAQPage Schema
How do I design a REST API with OpenAPI before coding?▼

Write an openapi.yaml file defining paths, schemas, and responses first, then use tools like Prism or Stoplight to generate a mock server from the spec. Stakeholders review the mock API before any implementation begins.

What is the best way to version a REST API?▼

URL versioning such as /api/v1/users is the most common and recommended approach. Header-based versioning via the Accept header is an option, while query parameter versioning should be avoided.

How do I solve the N+1 query problem in GraphQL?▼

Use DataLoader for batch loading to combine multiple resolver queries into single database calls. Combine this with query complexity limiting to prevent expensive nested queries from overloading the server.

How do I keep my API code and OpenAPI spec in sync?▼

Generate TypeScript types and interfaces directly from the spec using codegen tools, then run contract tests with tools like Dredd or Pact to verify the implementation matches the specification continuously.

When should I use GraphQL instead of REST?▼

GraphQL fits when clients need flexible queries with filters, pagination, and nested data via connections. REST with OpenAPI is better for simple CRUD resources, caching, and teams wanting mature tooling and contract testing.

Related Skills

Explore More Software Engineering Skills→
rachel353rachel353

conceptual-model

Generate a v2.0.0 conceptual model with entities, relationships, and domain rules.

Community
Intermediate
dotBeepsdotBeeps

api-design

Design REST and GraphQL API contracts with OpenAPI specifications and RFC 7807 errors.

Community
Advanced
Kushal9889Kushal9889

api-security-best-practices

Implements secure API authentication, authorization, input validation, rate limiting, and vulnerability protection.

Community
Advanced
gaebalaigaebalai

api-designer

Design REST, GraphQL, and gRPC APIs and generate OpenAPI specifications.

Community
Advanced