skills.rest
JayRHa
JayRHaCOMMUNITY
Explore all skills by this author →
Website𝕏@jannik_reinhardGitHub

api-designer

Design REST and GraphQL APIs with OpenAPI 3.1 or GraphQL SDL contracts.

3|2|Updated Jun 9, 2026
Search Tags:#design#versioning#api#openapi#rest#graphql#sdl
One-click install
npx skills add https://github.com/JayRHa/AgentSkills --skill api-designer-jayrha
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: api-designer
Source: https://github.com/JayRHa/AgentSkills/tree/main/api-designer
Command: npx skills add https://github.com/JayRHa/AgentSkills --skill api-designer-jayrha

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

Designs REST and GraphQL APIs that are consistent, evolvable, and pleasant for developers to use.

Core Features & Use Cases

  • Resource modeling and URI design guidance to ensure intuitive, scalable APIs.
  • Decision support for REST vs GraphQL vs RPC, versioning, pagination, filtering, and error contracts (RFC 9457).
  • OpenAPI 3.1 / GraphQL SDL contract generation and governance for machine-readable specifications.
  • Use cases include designing a new API, auditing an existing design, and establishing naming conventions and governance.

Quick Start

Propose an initial API design by outlining resources, endpoints, and error contracts.

Frequently Asked Questions about api-designer

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

FAQPage Schema
How do I design a REST API with consistent resource modeling and error contracts?▼

To design a REST API with consistent resource modeling, apply a contract-first approach using OpenAPI 3.1 and RFC 9457 problem details for standard error contracts. This ensures your API endpoints are intuitive, evolvable, and easy for clients to consume.

What is the best way to choose between REST, GraphQL, and RPC for a new API?▼

Choosing between REST, GraphQL, and RPC involves evaluating your data fetching complexity and client needs. This API design process provides decision support for selecting the right architectural style, ensuring your API is evolvable and appropriate for your specific use case.

How do I generate a machine-readable schema using GraphQL SDL and OpenAPI 3.1?▼

You can generate machine-readable schemas by adopting a contract-first approach that enforces OpenAPI 3.1 or GraphQL SDL specifications. This governance ensures your API design is consistent, machine-readable, and strictly documented for client integration.

How should I handle API versioning, pagination, and rate limiting in my design?▼

Handling API versioning, pagination, and rate limiting requires structured decision support during the design phase. By establishing these contracts early alongside idempotency and authentication rules, you ensure your API remains scalable and evolvable for future client needs.

Does this API design approach support auditing existing APIs for consistency?▼

Yes, this API design approach supports auditing existing APIs for consistency and governance. You can review an existing API design against established naming conventions, error contracts, and OpenAPI 3.1 or GraphQL SDL specifications to ensure it remains evolvable.

Related Skills

Explore More Software Engineering Skills→
mpadmarajmpadmaraj
2

api-design

Define REST API contracts with endpoints, HTTP methods, schemas, and error handling.

Community
Basic
Dokkabei97Dokkabei97
2

api-first-design

Design API contracts with OpenAPI and GraphQL schemas.

Community
Intermediate
erichowenserichowens
181

api-architect

Design and validate REST, GraphQL, and gRPC API contracts and architectures.

Community
Advanced
CharlieGreenmanCharlieGreenman
1

gpd-compare-results

Compare internal results against baselines to produce decisive verdicts.

Community
Advanced