api-designer

Design consistent REST and GraphQL APIs with OpenAPI specifications.

Updated Mar 27, 2026

Search Tags:#design #architecture #api #openapi #rest #graphql #schemas

Ready to run

npx skills add https://github.com/goodstoriesworld/coco-agent-skills --skill api-designer-goodstoriesworld

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: api-designer
Source: https://github.com/goodstoriesworld/coco-agent-skills/tree/main/vendored/api-designer
Command: npx skills add https://github.com/goodstoriesworld/coco-agent-skills --skill api-designer-goodstoriesworld

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Designing modern APIs can drift into inconsistent endpoints, vague schemas, and undocumented behaviors; this Skill provides a structured approach to enforce REST and GraphQL design best practices so teams ship coherent APIs.

Core Features & Use Cases

Design clean, consistent REST and GraphQL APIs across endpoints, schemas, and OpenAPI specs.
Provide guidance for resource modeling, HTTP methods, status codes, error handling, versioning, and documentation.
Use Case: When starting a new API for a product, align teams on naming conventions and OpenAPI spec before implementation.

Quick Start

Create a new API design for a sample resource (e.g., "books") including endpoints, schemas, and an OpenAPI skeleton.

Frequently Asked Questions about api-designer

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

FAQPage Schema

How do I design consistent REST and GraphQL APIs to prevent architectural drift?▼

To design consistent REST and GraphQL APIs, enforce resource modeling, HTTP method semantics, status codes, error handling, and versioning to standardize naming and documentation across endpoints.

What's the best way to align teams on OpenAPI specifications before implementation?▼

The best way to align on OpenAPI specifications is creating a structured design for resources including endpoints and schemas to enforce consistent naming conventions and architectural reviews.

When do I need to standardize HTTP methods and status codes in an API design?▼

You need to standardize HTTP methods and status codes when starting a new API to prevent vague schemas and undocumented behaviors, ensuring teams ship coherent REST and GraphQL architectures.

Can I use a structured approach to generate an OpenAPI skeleton from a resource model?▼

Yes, you can use a structured approach to generate an OpenAPI skeleton by defining resource modeling, schemas, and endpoints for a specific sample resource like books before implementation.

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

Yes, this API design approach works for both REST and GraphQL endpoints, enforcing consistent naming conventions, error handling, and versioning to prevent architectural drift across your schemas.

Why does my API architecture drift into inconsistent endpoints and schemas?▼

Your API architecture drifts into inconsistent endpoints and schemas due to a lack of structured enforcement for HTTP method semantics, error handling, and OpenAPI alignment during the design phase.