skills.rest
shalevamin
shalevaminCOMMUNITY
Explore all skills by this author →
GitHub

api-designer

Design RESTful and GraphQL APIs and generate OpenAPI 3.1 specifications.

Updated Mar 7, 2026
Search Tags:#error handling#api design#openapi#specification#rest#graphql#api architecture
One-click install
npx skills add https://github.com/shalevamin/The-_Ultimate_agents --skill api-designer-shalevamin
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: api-designer
Source: https://github.com/shalevamin/The-_Ultimate_agents/tree/main/.claude/skills/api-designer
Command: npx skills add https://github.com/shalevamin/The-_Ultimate_agents --skill api-designer-shalevamin

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

This Skill streamlines the complex process of designing RESTful or GraphQL APIs, ensuring adherence to best practices, generating clear specifications, and defining robust error handling.

Core Features & Use Cases

  • API Specification: Generates OpenAPI 3.1 specifications for REST APIs.
  • Resource Modeling: Assists in identifying and defining API resources and their relationships.
  • Error Handling: Defines consistent and informative error response patterns (e.g., RFC 7807).
  • Use Case: You need to design a new set of REST endpoints for a user management system. This Skill will help you define the resources, endpoints, request/response schemas, and error codes, producing a complete OpenAPI specification.

Quick Start

Use the api-designer skill to create an OpenAPI 3.1 specification for a new /users endpoint.

Frequently Asked Questions about api-designer

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

FAQPage Schema
How do I generate an OpenAPI 3.1 specification for new REST endpoints?▼

To generate an OpenAPI 3.1 specification for REST endpoints, you model API resources, define endpoints, and set request/response schemas. This enforces architectural patterns and versioning strategies for clear, maintainable contracts.

What is the best way to define consistent error handling in an API specification?▼

Defining API error handling involves establishing consistent and informative error response patterns, such as RFC 7807. This standardizes error reporting across endpoints, ensuring clients receive clear, structured feedback when operations fail.

Does this API design approach support both RESTful and GraphQL architectures?▼

Yes, the API design process supports both RESTful and GraphQL architectures. It models resources and defines endpoints for REST while enforcing consistent architectural patterns and error handling standards across both API paradigms.

How do I model resources and relationships for a user management API?▼

Modeling resources for a user management API involves identifying core entities and defining their relationships. This structures the API architecture, ensuring endpoints and schemas accurately reflect the domain's data interactions.

When do I need to enforce versioning strategies in my API design?▼

You need to enforce API versioning strategies when designing RESTful or GraphQL APIs to ensure maintainable contracts. Versioning manages breaking changes across iterations, keeping API interactions stable for existing clients.

Related Skills

Explore More Software Engineering Skills→
musujmusuj

phase-1-schema

Define project terminology, entities, relationships, and data structures.

Community
Intermediate
LLLLimboLLLLimbo

openapi-spec-generation

Generate and maintain OpenAPI 3.1 specifications from code and design-first inputs.

Community
Intermediate
AcczdyAcczdy
2

implementing-api-schema-validation-security

Enforce OpenAPI v3.x request and response schema validation against JSON Schema contracts.

Community
Advanced
curiositechcuriositech
181

api-architect

Validate OpenAPI 3.1, GraphQL, and Protobuf API specifications.

Official
Advanced