skills.rest
heimanba
heimanbaCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

api-and-interface-design

Design stable REST and GraphQL API contracts with typed schemas and error semantics.

2|Updated Apr 9, 2026
Search Tags:#interfaces#rest#graphql#error-handling#naming#contract-first#api-design
One-click install
npx skills add https://github.com/heimanba/port-lens --skill api-and-interface-design-heimanba
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: api-and-interface-design
Source: https://github.com/heimanba/port-lens/tree/main/.cursor/skills/api-and-interface-design
Command: npx skills add https://github.com/heimanba/port-lens --skill api-and-interface-design-heimanba

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Design stable, well-documented interfaces that are hard to misuse. Good interfaces make the right thing easy and the wrong thing hard. This applies to REST APIs, GraphQL schemas, module boundaries, component props, and any surface where one piece of code talks to another.

Core Features & Use Cases

  • Contract-first design: Define interfaces before implementation to guide development and prevent breaking changes.
  • Consistent error semantics: Establish uniform error handling across endpoints and services.
  • Boundary validation: Validate inputs at API boundaries and enforce contracts between systems and teams.

Quick Start

Propose a stable API contract for a new service by outlining endpoints, data schemas, and error formats in a concise, versioned spec.

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 when should I use it?▼

Contract-first API design defines typed interface contracts before implementation to guide development and prevent breaking changes. Use it for REST and GraphQL endpoints, module boundaries, and cross-team API handoffs to ensure stable, well-documented interfaces.

How do I design a stable REST API that won't break existing clients?▼

Design stable REST APIs by enforcing typed input/output schemas, consistent naming, and additive, backward-compatible changes. Establish uniform error semantics and validate inputs at API boundaries to make interfaces hard to misuse.

How do I standardize error handling across multiple microservices?▼

Standardize error handling by establishing uniform error semantics across endpoints and services. Apply consistent error formats and boundary validation to enforce contracts between systems and teams during cross-team API handoffs.

What's the best way to define module boundaries and cross-team API contracts?▼

Define module boundaries and cross-team API contracts using contract-first development. Outline endpoints, data schemas, and error formats in a concise, versioned spec to guide implementation and prevent breaking changes between systems.

Can I use this approach for both REST and GraphQL endpoint design?▼

Yes, this approach applies to both REST and GraphQL endpoint design. It enforces typed input/output schemas, consistent naming conventions, and additive, backward-compatible changes across any surface where one piece of code talks to another.

How do I validate inputs at API boundaries to enforce system contracts?▼

Validate inputs at API boundaries by enforcing typed input/output schemas and consistent error semantics. This boundary validation prevents invalid data from crossing system contracts and ensures interfaces remain hard to misuse.

Related Skills

Explore More Software Engineering Skills→
lexicalninjalexicalninja
2

technical-spec-writer

Generate technical specifications covering architecture, data models, API contracts, and deployment strategies.

Community
Advanced
hffmnnjhffmnnj
39

api-docs

Generate API reference documentation from OpenAPI specs and GraphQL schemas.

Community
Advanced
constellizeconstellize
1

write-contract-tests

Generate strict contract tests from constellation-map.md and code-generation-plan files.

Official
Advanced
Sake-TeamSake-Team

ai-first-engineering

Generate code output using AI-first engineering principles with explicit interfaces and deterministic testing.

Official
Advanced