api-design

Design and review REST APIs and OpenAPI specs with structured workflows.

Updated Jul 10, 2023
One-click install
npx skills add https://github.com/iamtatsuki05/dotfiles --skill api-design-iamtatsuki05
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: api-design
Source: https://github.com/iamtatsuki05/dotfiles/tree/main/dotfiles/.agent/skills/api-design
Command: npx skills add https://github.com/iamtatsuki05/dotfiles --skill api-design-iamtatsuki05

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

Designing robust REST APIs and OpenAPI specifications is error-prone and time-consuming without a structured workflow. This skill provides a comprehensive framework for designing, editing, validating, and reviewing API definitions to ensure consistency, security, versioning, and good usability.

Core Features & Use Cases

  • Workflow-driven API design: from requirements to spec creation, review, and validation.
  • OpenAPI/Swagger guidance: structuring paths, components, schemas, and security schemes.
  • Error handling and versioning: standard error formats and versioning strategies to support evolving APIs.

Quick Start

Describe your API design needs and I will generate an OpenAPI-compliant spec or review your REST endpoints.

Frequently Asked Questions about api-design

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

FAQPage Schema
How do I design and validate REST APIs using OpenAPI specifications?

To design and validate REST APIs, this skill enforces OpenAPI-compliant structures and guides you through editing endpoints, schemas, and security schemes to ensure production-ready consistency. It provides a structured workflow for reviewing paths and components.

What is the best way to structure error handling and versioning for REST APIs?

The best way to structure error handling and versioning is by applying standardized error formats and robust versioning strategies. This framework supports evolving APIs by enforcing consistent error definitions and structured version management across endpoints.

Can I use this to review existing Swagger definitions and security schemes?

Yes, you can review existing Swagger definitions by validating their OpenAPI structure, checking security schemes, and standardizing error handling. The skill guides the review workflow across endpoints, schemas, and versioning configurations.

How do I generate an OpenAPI-compliant spec from raw API requirements?

You generate an OpenAPI-compliant spec by describing your API design needs, which triggers a workflow that structures paths, components, and schemas. It translates requirements into validated, production-ready REST endpoints with robust security practices.

Does this approach enforce security practices for REST API endpoints?

Yes, the approach enforces robust security practices by validating OpenAPI security schemes and structuring them within your API definitions. It ensures that endpoints, schemas, and versioning follow standardized, production-ready security configurations.