skills.rest
goodstoriesworld
goodstoriesworldOFFICIAL
Explore all skills by this author →
WebsiteGitHub

api-designer

Design consistent REST and GraphQL APIs with OpenAPI specifications.

Updated Mar 27, 2026
Search Tags:#design#architecture#api#openapi#rest#graphql#schemas
One-click install
npx skills add https://github.com/goodstoriesworld/coco-agent-skills --skill api-designer-goodstoriesworld
Or copy as Structured Prompt for Agent▼
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.

Related Skills

Explore More Software Engineering Skills→
musujmusuj

phase-1-schema

Define project terminology, entities, relationships, and data structures.

Community
Intermediate
Dokkabei97Dokkabei97
2

api-first-design

Design API contracts with OpenAPI and GraphQL schemas.

Community
Intermediate
GaryOcean428GaryOcean428

api-design-validation

Validate REST API endpoint naming, HTTP methods, and status codes.

Community
Intermediate
EstomEstom

api-designer

Design REST and GraphQL APIs and generate OpenAPI 3.1 specifications.

Community
Advanced