api-and-interface-design

Designs stable REST APIs, TypeScript interfaces, and module contracts with consistent error semantics.

Updated Jul 9, 2026

Search Tags:#typescript #error handling #api design #rest #idempotency #pagination #interface contracts

Ready to run

npx skills add https://github.com/assafmanor/waypoint --skill api-and-interface-design-assafmanor

💬 Prompt for ChatGPT / Claude Chat▼

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

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Poorly designed interfaces create breaking changes, inconsistent error handling, and hidden dependencies that break consumers. This Skill guides the design of stable, hard-to-misuse APIs and module boundaries before implementation begins. ## Core Features & Use Cases - Contract-First Design: Define typed interfaces, REST endpoints, and error schemas before writing implementation code. - Idempotency Patterns: Implement idempotency keys correctly with atomic claims, payload guards, and retry-safe semantics for state-changing endpoints. - Backward Compatibility: Apply additive-only changes, consistent naming conventions, pagination, and boundary validation to avoid breaking consumers. - Use Case: When adding a new payments endpoint to your backend, use this Skill to define the request/response contract, error format, and idempotency behavior so client retries never cause duplicate charges. ## Quick Start Use the api-and-interface-design skill to design a REST API for managing trip itineraries with typed contracts and consistent error handling.

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

Define the contract first with typed input and output schemas, then evolve it by adding optional fields only. Never change existing field types or remove fields, and follow consistent naming conventions like plural nouns for endpoints and camelCase for fields.

How to implement idempotency keys for payment or POST endpoints?▼

Accept a client-generated Idempotency-Key header and claim it atomically using a database unique constraint, not a check-then-insert. Reject the same key reused with a different payload, and set key retention longer than the longest possible retry path.

Where should input validation happen in a web application?▼

Validate only at system boundaries: API route handlers, form submissions, environment variable loading, and third-party API responses. Internal functions that share type contracts should trust already-validated data rather than re-validating.

Should I use PUT or PATCH for updating resources?▼

Use PATCH for partial updates where only provided fields change, which is what clients typically need. PUT requires sending the full object every time and increases the risk of accidentally overwriting fields.

What is Hyrum's Law and why does it matter for API design?▼

Hyrum's Law states that all observable behaviors of an API will be depended on by someone, regardless of the documented contract. It means every public behavior is a commitment, so avoid leaking implementation details and plan deprecation at design time.