api-designer

Design REST and GraphQL APIs with OpenAPI 3.1 specifications.

Updated Jun 9, 2026
One-click install
npx skills add https://github.com/alsmadi99/dotfiles --skill api-designer-alsmadi99
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: api-designer
Source: https://github.com/alsmadi99/dotfiles/tree/main/claude/skills/api-designer
Command: npx skills add https://github.com/alsmadi99/dotfiles --skill api-designer-alsmadi99

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

Designers and engineers often struggle to translate business requirements into robust, versioned API contracts that are easy to document, test, and evolve.

Core Features & Use Cases

  • OpenAPI 3.1 contract design and validation for REST and GraphQL services.
  • Resource modeling, versioning strategies, pagination patterns, and RFC 7807 compliant error handling.
  • Templates and reference guidance to accelerate API specification, documentation, and mock validation with CI pipelines.
  • Example: Architect a new Users API with clear endpoints, schemas, and a migration plan.

Quick Start

Create an OpenAPI 3.1 spec for a small product API including endpoints, schemas, and error responses.

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 OpenAPI 3.1 specifications?

To design a REST API with OpenAPI 3.1, you model resources, define endpoints and schemas, and enforce consistent naming to produce accurate contracts and reliable integration documentation.

How do I handle pagination and error handling in GraphQL APIs?

Handle pagination and error handling in GraphQL APIs by applying scalable pagination patterns and RFC 7807 compliant error responses to ensure actionable and reliable service integration.

What is the best way to version REST API endpoints for scalable services?

The best way to version REST API endpoints is to apply versioning strategies during resource modeling to translate business requirements into robust, evolved API contracts.

Can I generate API documentation and mock validation for CI pipelines?

Yes, you can generate API documentation and mock validation with CI pipelines using templates and reference guidance to accelerate API specification and validate OpenAPI 3.1 compliance.

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

Yes, this API design approach works for both REST and GraphQL architectures, enforcing OpenAPI 3.1 compliance, resource modeling, and actionable error responses for scalable services.

Why do my API contracts struggle to evolve with business requirements?

API contracts struggle to evolve because designers often lack robust versioning strategies and RFC 7807 compliant error handling to accurately map changing business requirements.