apidesign

Define and validate stable API contracts for REST and GraphQL surfaces.

5|Updated May 2, 2026
One-click install
npx skills add https://github.com/vanducng/skills --skill apidesign
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: apidesign
Source: https://github.com/vanducng/skills/tree/main/skills/apidesign
Command: npx skills add https://github.com/vanducng/skills --skill apidesign

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Designing software surfaces before implementation to set clear interfaces, expectations, and change boundaries, preventing downstream breakages and misinterpretations.

Core Features & Use Cases

  • Contract-first design for REST/GraphQL surfaces
  • Precise input/output schemas, error models, and versioning posture
  • Use cases include defining new endpoints, module boundaries, and cross-team interfaces to avoid misalignment

Quick Start

Outline the API surface and contract semantics for a new service before coding

Frequently Asked Questions about apidesign

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

FAQPage Schema
What is contract-first API design and when do I need it?

Contract-first API design defines typed inputs, outputs, and a single error model before coding. You need it when establishing REST, GraphQL, or module boundaries to prevent downstream breakages and cross-team misalignment.

How do I define stable API contracts for REST and GraphQL surfaces?

Define stable API contracts by specifying precise input and output schemas, a unified error model, and an additive field evolution posture. This enforces clear interface semantics and prevents ambiguous boundaries across software projects.

Can I use this approach to define module boundaries and cross-team interfaces?

Yes, you can apply contract-first design to define module boundaries and cross-team interfaces. Outlining the API surface and contract semantics early prevents misinterpretation and sets clear change boundaries between separate software modules.

What's the best way to version API contracts and handle field evolution?

The best way to handle field evolution is adopting an additive posture, adding new fields without breaking existing consumers. This approach maintains stable API contracts by enforcing typed schemas and avoiding breaking changes.

Why does designing API surfaces before implementation prevent interface breakages?

Designing API surfaces before implementation prevents breakages by setting clear interfaces, expectations, and change boundaries upfront. This contract-first workflow eliminates ambiguous interfaces that cause downstream integration failures and team misalignment.