skills.rest
raishoemi
raishoemiCOMMUNITY
Explore all skills by this author →
GitHub

api-and-interface-design

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

Updated Jul 1, 2026
Search Tags:#typescript#api design#validation#rest#pagination#contract#interface
One-click install
npx skills add https://github.com/raishoemi/traffic-sim-v2 --skill api-and-interface-design-raishoemi
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: api-and-interface-design
Source: https://github.com/raishoemi/traffic-sim-v2/tree/main/.github/skills/api-and-interface-design
Command: npx skills add https://github.com/raishoemi/traffic-sim-v2 --skill api-and-interface-design-raishoemi

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, input/output schemas, and discriminated unions before writing implementation code. - REST API Conventions: Apply consistent patterns for resource naming, pagination, filtering, partial updates (PATCH), and structured error responses. - Boundary Validation: Enforce validation at system edges (API handlers, forms, third-party responses) while trusting internal typed code. - Use Case: When adding a new tasks endpoint to a web app, use this Skill to define the TaskAPI contract, standardize error shapes, add pagination, and ensure new fields are additive and backward compatible. ## Quick Start Use the api-and-interface-design skill to design a REST API contract for a task management endpoint with pagination 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 consumers?▼

Design REST APIs by preferring addition over modification: add only optional fields, never change existing field types or remove fields. Use plural noun endpoints, PATCH for partial updates, and paginate all list endpoints from the start.

What is the best way to structure API error responses?▼

Use one consistent error format across all endpoints: a machine-readable code, human-readable message, and optional details object. Map errors to standard HTTP status codes like 400, 401, 404, 409, and 422 without mixing patterns.

Should I validate data inside internal functions or at API boundaries?▼

Validate only at system boundaries where external input enters: API route handlers, form submissions, third-party responses, and environment variables. Internal functions that share type contracts should trust already-validated data.

When should I use PATCH instead of PUT for updates?▼

Use PATCH when clients should send only the fields they want to change, which is the common case. PUT requires sending the full object every time, making it fragile for partial updates and prone to overwriting unrelated 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 documented contracts. It means every public behavior is a commitment, so avoid leaking implementation details and plan deprecation at design time.

Related Skills

Explore More Software Engineering Skills→
hfadhlullahhfadhlullah

PRD Generator

Generate Product Requirements Documents through an interview process.

Community
Advanced
btabaskabtabaska
1

API Contract Test

Generate contract tests validating API endpoints against OpenAPI and TypeScript types.

Community
Intermediate
bseleebselee

security-review

Identify security vulnerabilities and compliance gaps in the MuRP codebase.

Community
Advanced
JayRHaJayRHa
3

api-designer

Design REST and GraphQL APIs with OpenAPI 3.1 or GraphQL SDL contracts.

Community
Advanced