skills.rest
j-cogburn
j-cogburnCOMMUNITY
Explore all skills by this author →
GitHub

api-and-interface-design

Design REST and GraphQL API contracts with consistent error semantics.

Updated Jun 1, 2026
Search Tags:#typescript#api#validation#rest#graphql#contracts#interface
One-click install
npx skills add https://github.com/j-cogburn/d3 --skill api-and-interface-design-j-cogburn
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: api-and-interface-design
Source: https://github.com/j-cogburn/d3/tree/main/tests/project-t01/.d3/skills/api-and-interface-design
Command: npx skills add https://github.com/j-cogburn/d3 --skill api-and-interface-design-j-cogburn

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This Skill eliminates the risk of building fragile, inconsistent, and easily misused APIs and module interfaces that lead to breaking changes, consumer confusion, and long-term technical debt.

Core Features & Use Cases

  • Core Design Principles: Enforces Hyrum's Law awareness, the One-Version Rule, contract-first design, consistent error semantics, boundary validation, and predictable naming conventions.
  • Pattern Libraries: Provides ready-to-use patterns for REST API resource design, pagination, filtering, partial updates, TypeScript discriminated unions, input/output separation, and branded types for IDs.
  • Use Cases: Ideal for designing REST or GraphQL endpoints, defining frontend-backend module boundaries, creating component prop interfaces, and aligning database schema shapes with API contracts.
  • Guardrails: Includes common rationalizations to avoid, red flags for fragile interface design, and a post-design verification checklist to ensure quality.

Quick Start

Use the api-and-interface-design skill to define typed, consistent contracts for your new task management API endpoints before writing any implementation code.

Frequently Asked Questions about api-and-interface-design

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

FAQPage Schema
What is contract-first API design and why does it prevent breaking changes?▼

Contract-first API design establishes typed, consistent interface contracts before writing implementation code, enforcing predictable naming and boundary validation to prevent breaking changes and consumer confusion.

Can I use TypeScript discriminated unions for REST and GraphQL error semantics?▼

Yes, TypeScript discriminated unions enforce consistent error semantics and input/output separation across REST and GraphQL boundaries, ensuring module interfaces remain stable and predictable for consumers.

How do I design REST API resource endpoints that resist misuse?▼

Design REST API resources using pattern libraries for pagination, filtering, and partial updates, while applying boundary validation and the One-Version Rule to ensure interfaces remain hard-to-misuse.

What is the best way to evolve frontend-backend module boundaries without breaking consumers?▼

Apply additive interface evolution and contract-first design to frontend-backend module boundaries, ensuring predictable naming and consistent error semantics to maintain long-term consumer trust without breaking changes.

When should I not use branded types for API interface contracts?▼

Avoid branded types for API contracts when post-design verification exposes red flags for fragile interface design, indicating that boundary validation or input/output separation may be insufficient for your scale.

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
mgd34msumgd34msu
4

openapi

Generate TypeScript types and client SDKs from OpenAPI 3.1 specifications.

Community
Advanced
pecorapromotionsllc-cellpecorapromotionsllc-cell

api-and-interface-design

Defines stable REST and GraphQL API contracts with typed inputs, outputs, and error semantics.

Community
Advanced
avgarciaavgarcia

openapi-spec-editor

Manage OpenAPI specification changes before implementation work begins.

Community
Advanced