API Interface Design Assistant

Problem

The main risk in API design is rarely whether one endpoint can be written; it is whether many endpoints share the same conventions: resource naming, query versus path parameters, pagination fields, and error response shapes. Inconsistent contracts increase frontend integration, mock preparation, and maintenance cost.

This skill turns a requirements description into a reviewable API design document. It targets inconsistent API style, misaligned response structures, and detached docs and examples.

How It Works

It organizes resource paths around RESTful rules: resources use plural nouns, actions are expressed through GET, POST, PUT, PATCH, and DELETE, and path depth should stay within three levels when possible. Versioning uses URL-based versions such as /api/v1/, and new fields are treated as non-breaking changes.

For output, it generates documentation around a common response shape, pagination rules, and a field template, and provides these artifacts:
- /gen-mock to generate mock data
- /gen-curl to generate curl examples
- /check-design to review design validity
- /gen-openapi to generate OpenAPI 3.0 YAML

Scope

It fits backend API design, API document review, pre-integration field alignment, and quick mock or curl example generation. It does not implement business logic, database migrations, permission systems, or production gateway configuration. If the project depends on private protocols, non-standard authentication, complex event streams, or special gateway routing, manual context is still required.