api-and-interface-design

Design contract-first REST and GraphQL APIs with consistent error semantics.

1|Updated Jan 28, 2025

Search Tags:#versioning #validation #error-handling #contract-first #api-design #rest-graphql #interface-design

Ready to run

npx skills add https://github.com/josuenavarroaguado/josuenavarroaguado.github.io --skill api-and-interface-design-josuenavarroaguado

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: api-and-interface-design
Source: https://github.com/josuenavarroaguado/josuenavarroaguado.github.io/tree/main/.github/skills/api-and-interface-design
Command: npx skills add https://github.com/josuenavarroaguado/josuenavarroaguado.github.io --skill api-and-interface-design-josuenavarroaguado

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Public interfaces and APIs often become fragile, inconsistent, or unintentionally relied upon due to unclear contracts, mixed error behaviors, and leaked implementation details. This Skill helps teams design stable, predictable interfaces that minimize accidental coupling and make breaking changes safe and deliberate.

Core Features & Use Cases

Contract-first approach: Define types and specs before implementation to make interfaces the source of truth.
Hyrum-aware design: Reduce accidental commitments by limiting observable behaviors and planning deprecation paths.
Consistent error semantics & validation: Standardize error shapes, status codes, and validate at system boundaries.
Backward compatibility: Prefer additive changes, support pagination, and avoid renaming or changing field types.
Applies to: REST and GraphQL endpoints, module boundaries, component props, internal service contracts, and APIs informed by database schemas.

Quick Start

Design a paginated REST endpoint for tasks by creating a contract-first specification, defining input and output types, a single consistent error schema, and validation at the API boundary.

Frequently Asked Questions about api-and-interface-design

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

FAQPage Schema

How do I design a stable REST API that avoids breaking changes?▼

To design a stable REST API, use a contract-first approach by defining types and specs before implementation, enforce additive backward-compatible changes, and avoid renaming or changing field types to minimize accidental coupling.

What is contract-first API design and when should I use it?▼

Contract-first API design makes interfaces and types the source of truth by defining specifications before implementation. Use it when creating or changing public surfaces like REST and GraphQL endpoints to prevent fragile, inconsistent behaviors.

How do I standardize error handling and validation at API boundaries?▼

Standardize error handling by defining consistent error shapes and status codes across your GraphQL or REST API. Validate inputs strictly at system boundaries to ensure predictable behavior and prevent leaked implementation details.

Does this approach work for designing GraphQL endpoints and module boundaries?▼

Yes, this interface design approach applies to GraphQL endpoints, REST APIs, module boundaries, component props, and internal service contracts, ensuring predictable naming conventions and consistent pagination across all public surfaces.

How do I reduce accidental coupling in public interfaces?▼

Reduce accidental coupling in public interfaces by applying Hyrum-aware design, which limits observable behaviors and plans deliberate deprecation paths. This prevents users from unintentionally relying on leaked implementation details.