skills.rest
nexus-substrate
nexus-substrateOFFICIAL
Explore all skills by this author →
GitHub

api-and-interface-design

Design stable API contracts with typed schemas and consistent error semantics.

18|1|Updated Jan 3, 2026
Search Tags:#type safety#api design#schema validation#interface contracts#mcp tools#error semantics#untrusted input
One-click install
npx skills add https://github.com/nexus-substrate/nexus-agents --skill api-and-interface-design-nexus-substrate
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: api-and-interface-design
Source: https://github.com/nexus-substrate/nexus-agents/tree/main/skills/api-and-interface-design
Command: npx skills add https://github.com/nexus-substrate/nexus-agents --skill api-and-interface-design-nexus-substrate

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

It prevents fragile integrations and hidden coupling by ensuring every API surface has a clear, consistent contract, validation strategy, and error semantics from the start.

Core Features & Use Cases

  • Contract-first interface design: Define types and boundaries before implementation so the interface is the spec.
  • Consistent error and result semantics: Use one error strategy per surface (not a mix), including nexus-agents’ canonical Result<T, E> pattern for tool handlers.
  • Boundary validation and untrusted input hardening: Validate MCP tool input, HTTP requests, and third-party responses at entry points using typed schemas (e.g., Zod), while trusting internal modules afterward.
  • Consumer-focused types: Prefer discriminated unions over flag fields, separate input/output shapes, and use branded ID types to reduce misuse.

Quick Start

Ask the AI to redesign the new endpoint or MCP tool contract by proposing typed inputs/outputs, selecting a single error strategy, and specifying exactly where boundary validation should happen.

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 stable API contracts that are hard to misuse?▼

Stable API contracts require defining typed schemas, consistent error semantics, and boundary validation before implementation. By applying contract-first development and separating input/output shapes, you create interfaces that prevent fragile integrations and reduce consumer misuse.

How do I validate untrusted input for MCP tools and HTTP endpoints?▼

Validate untrusted input at entry points using typed schemas like Zod. This boundary validation hardens HTTP requests and MCP tool inputs against invalid data, while internal modules remain trusted afterward to avoid redundant checks.

What is the best way to handle error semantics across API surfaces?▼

Error semantics should use one consistent error strategy per API surface rather than a mix. Applying a canonical Result<T, E> pattern for tool handlers ensures consistent error and result semantics across the entire interface.

How do I safely evolve existing API interfaces without breaking consumers?▼

Safely evolving existing interfaces involves designing consumer-focused types, preferring discriminated unions over flag fields, and using branded ID types. This minimizes hidden coupling and ensures stable contract evolution.

Does contract-first API design work with database-to-API shaping?▼

Contract-first design applies to database-to-API shaping by defining typed schemas and boundary validation at the module boundary. This ensures the interface is the spec, preventing hidden coupling between database and API layers.

Related Skills

Explore More Software Engineering Skills→
ax-llmax-llm
2.9k

ax-rust-signature

Generate Rust Ax signature code and JSON schema for typed contracts.

Official
Intermediate
dthompsonfldthompsonfl

zod-validation

Validate and sanitize incoming data with Zod schemas in Next.js 16 App Router.

Community
Advanced
MolcajeteAIMolcajeteAI
2

type-safety-patterns

Implement TypeScript type guards, generics, branded types, and discriminated unions.

Official
Advanced
svssdevasvssdeva
1

api-and-interface-design

Design stable REST and GraphQL interfaces with contract-first typing and additive versioning.

Community
Advanced