API Designer

Design REST and GraphQL APIs with OpenAPI 3.1 specifications.

Updated Oct 22, 2025
One-click install
npx skills add https://github.com/franroa/chezmoi --skill api-designer-franroa
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: API Designer
Source: https://github.com/franroa/chezmoi/tree/main/private_dot_config/opencode/skills/api-designer
Command: npx skills add https://github.com/franroa/chezmoi --skill api-designer-franroa

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This Skill helps teams architect REST and GraphQL APIs with clear contracts, consistent patterns, and developer-friendly specs.

Core Features & Use Cases

  • OpenAPI specifications: Create comprehensive OpenAPI 3.1 contracts.
  • Resource modeling & versioning: Define resources, relationships, and deprecation plans.
  • Error handling & authentication design: Standardize error schemas and auth flows.

Quick Start

Propose an OpenAPI 3.1 spec for a sample blog API with endpoints for posts, comments, and users, including authentication 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 that follows OpenAPI 3.1 standards?

REST API design with OpenAPI 3.1 involves defining resource endpoints, HTTP methods, request/response schemas, and authentication flows in a machine-readable contract. This Skill guides you through creating comprehensive OpenAPI specs that enforce REST principles, consistent naming conventions, and clear endpoint documentation to ensure developers can integrate reliably.

What's the best way to handle versioning and deprecation in API design?

API versioning strategies balance backward compatibility with evolution. This Skill covers versioning policies, deprecation planning, and resource modeling to help you maintain stable contracts while introducing changes, ensuring existing integrations continue working as you roll out new capabilities.

How should I structure error responses in my API?

Standardized error handling improves developer experience and debugging. This Skill enforces RFC 7807 error response schemas across REST and GraphQL, so clients receive consistent, actionable error information including status codes, error types, and recovery guidance.

Can I design both REST and GraphQL APIs with consistent patterns?

Yes. This Skill covers API design for both REST and GraphQL architectures, helping you define resource models, authentication schemes, pagination strategies, and rate limiting considerations that work across both paradigms for consistent developer experience.

What authentication and security considerations should I plan for in API design?

API security begins in design. This Skill includes authentication flow planning, security disclosure strategies, and rate limiting considerations to help you architect APIs that protect data, prevent abuse, and communicate security requirements to developers upfront.

How do I implement pagination and rate limiting in API specifications?

Pagination strategies and rate limiting protect both client and server. This Skill helps you define pagination approaches, enforce consistent request patterns, and document rate limits in your OpenAPI specifications so developers build compliant integrations.