skills.rest
DagimAlemayehuu
DagimAlemayehuuCOMMUNITY
Explore all skills by this author →
GitHub

api-and-interface-design

Design stable REST APIs, TypeScript contracts, and module boundaries with consistent error semantics.

Updated Jul 19, 2026
Search Tags:#typescript#error handling#api design#validation#rest#pagination#interface contracts
One-click install
npx skills add https://github.com/DagimAlemayehuu/AgenticEngineering --skill api-and-interface-design-dagimalemayehuu
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: api-and-interface-design
Source: https://github.com/DagimAlemayehuu/AgenticEngineering/tree/main/agentic-engineering/core/dependencies/planning/api-and-interface-design
Command: npx skills add https://github.com/DagimAlemayehuu/AgenticEngineering --skill api-and-interface-design-dagimalemayehuu

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Public interfaces become hard to change once consumers depend on them, and inconsistent error handling, missing pagination, or breaking field changes silently break downstream clients. This Skill provides concrete design rules and code patterns for building APIs and module contracts that stay stable as they evolve. ## Core Features & Use Cases - Contract-First Design: Define TypeScript interfaces, input/output separation, discriminated unions, and branded ID types before implementation. - REST API Patterns: Standard resource naming, pagination, filtering, and PATCH-based partial updates with predictable conventions. - Consistent Error Semantics: A single structured error shape mapped to HTTP status codes, plus boundary-only validation rules including untrusted third-party responses. - Use Case: When adding a new endpoint to a task management service, use this Skill to define the typed contract, error format, and pagination scheme before writing any handler code. ## Quick Start Use the api-and-interface-design skill to design the REST endpoints and TypeScript contracts for a new comments resource on my task API.

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?▼

Prefer addition over modification: add new fields as optional and never change or remove existing field types. Use PATCH for partial updates, paginate list endpoints from the start, and treat every observable behavior as a commitment under Hyrum's Law.

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

Pick one error strategy and use it everywhere: a structured body with a machine-readable code, human-readable message, and optional details, mapped to standard HTTP status codes like 400, 422, and 409. Never mix throwing, returning null, and error objects across endpoints.

Where should input validation happen in an API?▼

Validate only at system boundaries: route handlers, form submissions, environment variables, and third-party API responses, which must always be treated as untrusted. Internal functions that share type contracts should trust already-validated data.

Should I use PUT or PATCH for updating resources?▼

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

When should I version my API?▼

Design for extension from the start so breaking changes are unnecessary, following the One-Version Rule to avoid diamond dependency problems. Additive, optional changes let a single version serve all consumers without maintaining parallel versions.

Related Skills

Explore More Software Engineering Skills→
hpsgdhpsgd

write-spec

Generate specification documents with user stories, acceptance criteria, API contracts, and data models.

Official
Advanced
YokhanYokhan

api-contract

Verify API implementations against documented contracts and report mismatches.

Community
Advanced
logo-solutionslogo-solutions

security-and-hardening

Harden web applications against security vulnerabilities in input handling, authentication, and data storage.

Official
Advanced
sirnsirn

code-design-api

Plan API contracts and schemas for REST, GraphQL, or RPC endpoints.

Community
Advanced