skills.rest
japurcell
japurcellCOMMUNITY
Explore all skills by this author →
GitHub

addy-api-and-interface-design

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

Updated Mar 19, 2026
Search Tags:#design#architecture#api#validation#interface#contract-first
One-click install
npx skills add https://github.com/japurcell/skills --skill addy-api-and-interface-design
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: addy-api-and-interface-design
Source: https://github.com/japurcell/skills/tree/main/skills/addy-api-and-interface-design
Command: npx skills add https://github.com/japurcell/skills --skill addy-api-and-interface-design

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Designing public and internal interfaces without explicit contracts leads to misuse, breaking changes, and integration risk across teams and systems.

Core Features & Use Cases

  • Contract-first interface definitions to establish clear boundaries between modules and services.
  • Consistent error semantics and validation at API boundaries to reduce surprises for clients.
  • Guidelines for naming, versioning, and evolution that enable safe, backward-compatible changes.

Quick Start

Formulate the contract first: define input/output schemas and error contracts, then implement against them and validate against the contract.

Frequently Asked Questions about addy-api-and-interface-design

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

FAQPage Schema
What is a contract-first API design approach and when should I use it?▼

Contract-first API design defines input/output schemas and error contracts before implementation. Use it to establish clear boundaries between modules and services, minimizing misuse and integration risk across frontend-backend boundaries.

How do I design stable module boundaries to prevent breaking changes?▼

Design stable module boundaries by applying consistent error semantics, boundary validation, and backward-compatible evolution guidelines. This minimizes misuse and prevents breaking changes across team boundaries and public interfaces.

Can I apply consistent API validation rules across both REST and GraphQL boundaries?▼

Yes, consistent API validation and error semantics apply to REST, GraphQL, and inter-service contracts. Enforcing boundary validation across these protocols reduces surprises for clients consuming the public interfaces.

What is the best way to evolve an interface safely without breaking existing clients?▼

The best way to evolve an interface safely is to enforce backward-compatible changes using clear naming patterns and versioning guidelines. This minimizes misuse risk while maintaining stable API surfaces for existing clients.

Does this approach work for inter-service contracts across team boundaries?▼

Yes, this approach explicitly applies to inter-service contracts across team boundaries and public interfaces. It enforces contract-first definitions and consistent validation to reduce integration risk between separate teams.

Related Skills

Explore More Software Engineering Skills→
HZeroxiumHZeroxium

java-api-design-rest

Design REST APIs with resource modeling, pagination, and RFC 9457 errors.

Community
Advanced
enchantednaturesenchantednatures

api-design

Design standardized REST, GraphQL, and gRPC APIs with versioning and error handling.

Community
Advanced
vtgiang-dotcomvtgiang-dotcom
3

api-patterns

Define REST and GraphQL APIs with consistent contracts and validation.

Community
Advanced
nexus-substratenexus-substrate
18

api-and-interface-design

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

Official
Advanced