skills.rest
yknothing
yknothingCOMMUNITY
Explore all skills by this author →
GitHub

api-design

Define stable API contracts with OpenAPI or Protobuf documentation.

1|Updated Mar 17, 2026
Search Tags:#architecture#versioning#documentation#openapi#backward-compatibility#contracts#api-design
One-click install
npx skills add https://github.com/yknothing/prodcraft --skill api-design-yknothing
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: api-design
Source: https://github.com/yknothing/prodcraft/tree/main/skills/02-architecture/api-design
Command: npx skills add https://github.com/yknothing/prodcraft --skill api-design-yknothing

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

API design governs how components communicate, ensuring stable boundaries and evolvable contracts that minimize breaking changes across releases.

Core Features & Use Cases

  • Choose API style (REST, GraphQL, gRPC, event-driven) and justify it based on consumer needs.
  • Model resources with clear boundaries, naming, and versioning rules to support brownfield and greenfield efforts.
  • Document contracts with OpenAPI or protobuf, including error handling, schemas, and migration guidelines.
  • Use open questions to capture assumptions around authorization, rollout, and compatibility.

Quick Start

Draft an OpenAPI specification for a hypothetical /v1/orders resource with standard CRUD operations.

Frequently Asked Questions about api-design

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

FAQPage Schema
How do I design API contracts that support future evolution without breaking changes?▼

To design API contracts that support future evolution, you must define clear resource boundaries, enforce backward-compatibility rules, and document versioning strategies. This approach minimizes breaking changes across releases.

What is the best way to choose between REST, GraphQL, and gRPC for API design?▼

The best way to choose an API style like REST, GraphQL, gRPC, or event-driven is to justify the selection based on specific consumer needs. This ensures the architecture boundaries align with client requirements.

How do I document API schemas and error handling using OpenAPI?▼

You document API schemas and error handling using OpenAPI by defining standard CRUD operations, explicit schemas, and migration guidelines. This captures contract specifications and authorization assumptions.

Can I apply API contract modeling to existing brownfield projects?▼

Yes, you can apply API contract modeling to brownfield projects. The process supports both brownfield and greenfield efforts by establishing clear naming, versioning rules, and resource boundaries for existing systems.

What open questions should I capture for API rollout and migration strategies?▼

You should capture open questions regarding authorization, rollout, and migration strategies. Addressing these compatibility assumptions explicitly ensures stable boundaries and evolvable contracts across releases.

Related Skills

Explore More Software Engineering Skills→
Fr-e-dFr-e-d
157

architecture-extract

Analyze project directory structures to generate architectural summaries.

Community
Basic
AI-Foundry-CoreAI-Foundry-Core
4

openapi-spec-generation

Generate OpenAPI 3.1 specifications from code and design artifacts.

Official
Advanced
heaptracetechnologyheaptracetechnology
13

contract-test

Automate API contract testing with schema validation and OpenAPI checks.

Community
Advanced
ginkidaginkida
20

openapi-expert

Design, validate, and generate code from OpenAPI 3.x specifications.

Community
Advanced