api-and-interface-design

Design REST and GraphQL APIs with consistent error semantics and predictable naming.

Updated May 14, 2026

Search Tags:#api design #rest #graphql #interface design #type-safe

Ready to run

npx skills add https://github.com/soloamente/still --skill api-and-interface-design-soloamente

💬 Prompt for ChatGPT / Claude Chat▼

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

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) and references (resource) components.

What problem does it solve?

This Skill helps you design stable, well-documented APIs and interfaces, making the right thing easy and the wrong thing hard. It's useful when creating REST or GraphQL endpoints, defining type contracts, and establishing boundaries between components.

Core Features & Use Cases

API Design: Guidance for designing APIs with Hyrum's Law, the One-Version Rule, and Contract-First principles.
Interface Design: Best practices for creating interfaces with consistent error semantics, boundary validation, and predictable naming.
REST API Patterns: Resource design, pagination, filtering, and partial updates examples.
TypeScript Interface Patterns: Using Discriminated Unions, Input/Output Separation, and Branded Types.
Common Rationalizations: Addressing common misconceptions about API and interface design.

Quick Start

Use the api-and-interface-design skill to guide your API design process with Hyrum's Law and consistent error handling principles.

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 stable REST API endpoints that don't break existing clients?▼

Design stable REST API endpoints using Contract-First principles and the One-Version Rule. This approach ensures predictability by making the right usage easy and preventing breaking changes, applying Hyrum's Law to maintain robust client compatibility.

What is the best way to structure consistent error semantics for an API?▼

Structure consistent API error semantics by enforcing boundary validation and predictable naming conventions. This ensures interfaces fail predictably, making it harder to misuse endpoints while maintaining clear, stable type contracts across system boundaries.

How do I create type-safe TypeScript interfaces for component props?▼

Create type-safe TypeScript interfaces using Discriminated Unions, Input/Output Separation, and Branded Types. These patterns establish strict module boundaries, ensuring predictable data shapes and preventing invalid prop combinations at compile time.

What REST API patterns should I use for pagination and partial updates?▼

Use specific REST API patterns for resource design, pagination, filtering, and partial updates. These patterns provide standardized, predictable interfaces for managing large datasets and modifying resources without full payload replacements.

Does this API design guidance work for GraphQL endpoints as well as REST?▼

Yes, this API design guidance applies to both GraphQL and REST endpoint design. It focuses on universal design principles like Hyrum's Law, stability, and consistency, ensuring type-safe and predictable interfaces regardless of the specific protocol.

When should I apply Hyrum's Law to interface design?▼

Apply Hyrum's Law to interface design whenever you establish module boundaries or component prop interfaces. It addresses common rationalizations by ensuring that all observable behaviors become contractual, preventing unintended dependencies on implementation details.