api-and-interface-design

Design REST and GraphQL APIs with stable, documented patterns.

Updated Jul 7, 2026

Search Tags:#software development #api design #graphql #interface design #rest api

Ready to run

npx skills add https://github.com/reez455G/my-ai-agents --skill api-and-interface-design-reez455g

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: api-and-interface-design
Source: https://github.com/reez455G/my-ai-agents/tree/main/.omp/skills/api-and-interface-design
Command: npx skills add https://github.com/reez455G/my-ai-agents --skill api-and-interface-design-reez455g

SYSTEM DOCUMENTATION & REQUIREMENTS

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

What problem does it solve?

This Skill helps developers design stable, well-documented APIs and interfaces that are easy to use and maintain.

Core Features & Use Cases

API Design Principles: Follows Hyrum's Law, the One-Version Rule, and emphasizes contract-first design.
REST API Patterns: Offers guidance on resource design, pagination, filtering, and partial updates.
TypeScript Interface Patterns: Covers input/output separation and discriminative unions for variants.
Common Rationalizations: Addresses common misconceptions about API design.

Quick Start

Design your next REST API or GraphQL schema using this Skill to ensure your interfaces are robust and maintainable.

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 should I use it?▼

Contract-first API design defines the interface contract before implementation, ensuring stable and well-documented APIs. Use it to maintain robust REST and GraphQL interfaces by emphasizing principles like the One-Version Rule and preventing breaking changes.

How do I design REST APIs for pagination, filtering, and partial updates?▼

Design REST APIs for pagination, filtering, and partial updates by following established resource design patterns. This approach ensures your API remains maintainable and easy to use while addressing complex data retrieval requirements effectively.

What's the best way to structure TypeScript interfaces for variant outputs?▼

Structure TypeScript interfaces using discriminative unions for variants and maintaining input/output separation. This method creates robust, well-documented interfaces that prevent runtime errors and improve overall maintainability.

How does Hyrum's Law affect interface design and API stability?▼

Hyrum's Law affects interface design by noting that observable implementation details become implicit dependencies. Understanding this helps developers create stable APIs by anticipating how users might rely on undocumented behaviors.

Do I need prior programming knowledge to implement GraphQL schema best practices?▼

Yes, implementing GraphQL schema best practices requires understanding of interface design principles and programming languages. This foundational knowledge is necessary to apply the stable, well-documented design patterns effectively.

What are common misconceptions and rationalizations in API design?▼

Common API design misconceptions often justify poor interface choices by overlooking long-term maintainability. Addressing these rationalizations helps developers adhere to contract-first principles and avoid creating brittle, difficult-to-use APIs.