skills.rest
RefractSystems
RefractSystemsOFFICIAL
Explore all skills by this author →
GitHub

api-and-interface-design

Guide contract-first API design for REST and GraphQL endpoints.

Updated Aug 27, 2026
Search Tags:#api design#validation#rest#graphql#interface design#error-handling#contract-first
One-click install
npx skills add https://github.com/RefractSystems/virtmcu --skill api-and-interface-design-refractsystems
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: api-and-interface-design
Source: https://github.com/RefractSystems/virtmcu/tree/main/.gemini/skills/api-and-interface-design
Command: npx skills add https://github.com/RefractSystems/virtmcu --skill api-and-interface-design-refractsystems

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Designing APIs and interfaces without clear contracts leads to brittle integrations, unexpected consumer dependencies, and costly breaking changes; this Skill helps teams avoid those pitfalls by establishing intentional, discoverable, and maintainable interface contracts.

Core Features & Use Cases

  • Contract-first design: Define input/output schemas and behaviors before implementation to make the API the source of truth.
  • Consistent error semantics: Standardize error shapes and HTTP status mappings so consumers can handle failures predictably.
  • Boundary validation: Validate untrusted inputs at system edges and trust internal contracts to reduce defensive duplication.
  • Backward-compatible evolution: Prefer additive changes, plan deprecation, and follow the One-Version Rule to avoid dependency fragmentation.
  • Practical patterns: REST resource design, pagination, filtering, PATCH semantics, discriminated unions in TypeScript, and branded ID types.

Quick Start

Create a contract-first API spec for a task resource that defines input and output schemas, consistent error formats, pagination, and a deprecation strategy.

Frequently Asked Questions about api-and-interface-design

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
What is contract-first API design and why should I use it?▼

Contract-first API design defines input/output schemas and behaviors before implementation, making the API the source of truth. This prevents brittle integrations and unexpected consumer dependencies by establishing discoverable, maintainable interface contracts upfront.

How do I design backward-compatible REST and GraphQL APIs?▼

To design backward-compatible REST and GraphQL APIs, prefer additive changes, plan deprecation strategies, and follow the One-Version Rule. This prevents dependency fragmentation by ensuring consistent extension rules and predictable naming conventions across endpoints.

How do I standardize error handling and HTTP status mappings?▼

Standardize error handling by creating consistent error semantics that map failures to predictable HTTP status codes. This allows API consumers to handle failures predictably by standardizing error shapes across all REST and GraphQL endpoints.

Where should I validate untrusted inputs in my API architecture?▼

Validate untrusted inputs at system edges using boundary validation. By validating data at the API boundary and trusting internal contracts, you reduce defensive duplication and maintain clean module boundaries throughout your architecture.

Can I use this for database-informed schema design and TypeScript types?▼

Yes, you can apply this to database-informed schema design, module boundaries, and component props. It supports practical patterns like discriminated unions in TypeScript and branded ID types to ensure stable, well-documented interface contracts.

Related Skills

Explore More Software Engineering Skills→
nicholasgriffintnnicholasgriffintn
2

backend-design

Plan backend systems, APIs, and data models with structured architecture decisions.

Community
Basic
Dokkabei97Dokkabei97
2

api-first-design

Design API contracts with OpenAPI and GraphQL schemas.

Community
Intermediate
abdullah1854abdullah1854
1

api-test-gen

Generate Jest/Supertest or Pytest test templates for REST endpoints.

Community
Advanced
CiabatosCiabatos

rpg-sql-generator

Generate PostgreSQL migration scripts for RPG game database features.

Community
Advanced