skills.rest
huangzida
huangzidaCOMMUNITY
Explore all skills by this author →
GitHub

api-and-interface-design

Design stable REST and GraphQL APIs with contract-first practices.

2|1|Updated Mar 26, 2026
Search Tags:#design#api#interfaces#rest#graphql#contracts
One-click install
npx skills add https://github.com/huangzida/skills --skill api-and-interface-design-huangzida
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: api-and-interface-design
Source: https://github.com/huangzida/skills/tree/main/api-and-interface-design
Command: npx skills add https://github.com/huangzida/skills --skill api-and-interface-design-huangzida

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Design stable, well-documented interfaces that are hard to misuse and easy to evolve, preventing brittle integrations across teams.

Core Features & Use Cases

  • Contract-First Design: Define the surface of APIs and module boundaries before implementation to align teams.
  • Consistent Error Semantics: Establish standardized error shapes and status mappings for reliable client handling.
  • Boundary Validation: Enforce contracts at API edges to protect internal invariants and reduce coupling.
  • Use Case: When designing REST or GraphQL endpoints, or establishing contracts between frontend and backend teams.

Quick Start

Start by drafting a clear API contract before coding, then implement against it using typed interfaces and basic validations.

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 when do I need it for REST or GraphQL?▼

Contract-first API design means defining the surface of REST or GraphQL endpoints and module boundaries before implementation. You need it to align frontend and backend teams, prevent misuse, and avoid brittle integrations across inter-team contracts.

How do I design stable APIs that do not break existing frontend integrations?▼

Design stable APIs by enforcing additive changes, consistent error semantics, and boundary validation at API edges. Establishing standardized error shapes protects internal invariants and ensures frontend integrations do not break when backend endpoints evolve.

How do I establish consistent error semantics for REST and GraphQL endpoints?▼

Establish consistent error semantics for endpoints by defining standardized error shapes and status mappings. This provides reliable client handling and reduces coupling between frontend and backend teams across inter-team contracts.

What is the best way to enforce module boundaries and reduce coupling between teams?▼

The best way to enforce module boundaries is applying boundary validation at API edges to protect internal invariants. Defining clear inter-team contracts before coding reduces coupling and prevents misuse across frontend and backend integrations.

Does this approach work for both REST and GraphQL inter-team contracts?▼

Yes, this contract-first design approach works for both REST and GraphQL endpoints. It enforces naming conventions, additive changes, and boundary validation to establish reliable inter-team contracts across frontend and backend module boundaries.

Related Skills

Explore More Software Engineering Skills→
cookeyholdercookeyholder

api-and-interface-design

Define stable REST or GraphQL API contracts before implementation.

Community
Intermediate
nrakownrakow
1

data-contracts

Define and enforce YAML data contracts for dbt models in CI.

Community
Advanced
japurcelljapurcell

addy-api-and-interface-design

Design stable API surfaces and module boundaries for REST, GraphQL, and inter-service contracts.

Community
Advanced
nexus-substratenexus-substrate
18

api-and-interface-design

Design stable API contracts with typed schemas and consistent error semantics.

Official
Advanced