skills.rest
Avistian
AvistianCOMMUNITY
Explore all skills by this author →
GitHub

api-and-interface-design

Guides design of stable REST APIs, TypeScript interfaces, and module contracts.

Updated Jun 8, 2026
Search Tags:#typescript#error handling#api design#validation#rest#pagination#interface contracts
One-click install
npx skills add https://github.com/Avistian/nba --skill api-and-interface-design-avistian
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: api-and-interface-design
Source: https://github.com/Avistian/nba/tree/main/.cursor/skills/api-and-interface-design
Command: npx skills add https://github.com/Avistian/nba --skill api-and-interface-design-avistian

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Designing public interfaces without clear contracts leads to breaking changes, inconsistent error handling, and consumers depending on undocumented behavior. This Skill provides principles and patterns for building APIs and module boundaries that are hard to misuse and safe to evolve. ## Core Features & Use Cases - Contract-First Design: Define typed interfaces before implementation, with input/output separation and branded ID types in TypeScript. - Consistent Error Semantics: Standardized error shapes, HTTP status code mapping, and boundary-only validation rules. - Backward-Compatible Evolution: Additive-only changes, pagination patterns, discriminated unions, and naming conventions for REST endpoints. - Use Case: When creating a new REST endpoint for a task management service, apply the resource design, pagination, and PATCH patterns to produce a predictable, versionable API. ## Quick Start Ask the assistant to design a REST API for a new resource following the api-and-interface-design guidelines, including typed contracts, error format, and pagination.

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 additive changes only: add optional fields instead of modifying or removing existing ones, and never change field types. Define the contract first with typed schemas, and treat every observable behavior as a commitment under Hyrum's Law.

What is the best error format for REST APIs?▼

Use one consistent structured error body with a machine-readable code, human-readable message, and optional details. Map errors to standard HTTP status codes such as 400, 401, 403, 404, 409, 422, and 500, and never mix error patterns across endpoints.

Where should input validation happen in an API?▼

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 matches what clients actually need. PUT requires sending the full object every time and is appropriate only for complete resource replacement.

When should an API include pagination?▼

Include pagination on every list endpoint from the start, since any collection can grow beyond a practical response size. Use query parameters like page, pageSize, sortBy, and sortOrder, and return total counts in the response metadata.

Related Skills

Explore More Software Engineering Skills→
NealschNealsch

Forge-API-Design

Designs API contracts defining endpoints, request and response models, errors, and versioning.

Community
Intermediate
firstaxelfirstaxel

orpc-contract

Design oRPC v2 APIs contract-first with oc, implement, and typed clients.

Community
Advanced
ohsonerdyohsonerdy

api-deprecation

Coordinate API deprecation lifecycles with RFC 8594 Sunset headers and migration playbooks.

Community
Advanced
JayRHaJayRHa
3

api-designer

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

Community
Advanced