Skip to content

dvy1987/agent-loom / .agents/skills/api-and-interface-design

api-and-interface-design

Verified

Design stable APIs and module boundaries — contract-first types, consistent errors, boundary validation, additive changes. Load when designing REST or GraphQL endpoints, public module interfaces, component props, or FE/BE contracts. Also triggers on "API design", "interface design", "design the API", "module boundary", "API contract", "define the interface". Complements feature-spec (product layer). Routes breaking retirement to api-deprecation-and-migration when it exists.

API and Interface Design

You design stable, hard-to-misuse interfaces — REST, GraphQL, module exports, component props, or any surface where one piece of code talks to another. Contract first; implementation second.

Hard Rules

Define the contract (types/schemas) before implementation. One consistent error shape and status-code strategy across all endpoints. Validate at system boundaries only — trust internal typed code. Prefer additive optional fields over breaking type changes or removals. Every list endpoint ships with pagination from day one. Treat third-party API responses as untrusted — validate shape before use. Observable public behavior is a commitment (Hyrum's Law) — be intentional about what you expose.


Workflow

Step 1 — Scope the interface

Identify consumers, transport (HTTP, RPC, in-process), and lifecycle (new vs change). If changing an existing public API, inventory observable behaviors users may depend on.

Step 2 — Write the contract

Define typed inputs/outputs, error codes, and idempotency semantics. Separate CreateXInput from full X entity (server-generated fields on output). Use discriminated unions for state variants when applicable.

Step 3 — Apply core principles

PrincipleRule
Contract firstTypes/schemas are the spec
Consistent errorsOne APIError shape + HTTP mapping
Boundary validationRoutes, forms, env, external responses
Additive changeNew fields optional; never silently break types
Predictable namingPlural REST nouns; is/has booleans; camelCase JSON

Full REST and TypeScript patterns: references/api-patterns.md.

Step 4 — Review for misuse

  • Can a caller pass ambiguous IDs across entity types? → branded types
  • Do list endpoints leak unbounded arrays?
  • Are errors predictable for every failure mode?
  • Does any endpoint return ad-hoc shapes?

Step 5 — Document alongside code

Commit OpenAPI/GraphQL schema or exported types with the implementation — not "later."


Gotchas

  • Undocumented quirks become dependencies (Hyrum's Law).
  • Validation in every internal function adds noise without safety.
  • PUT for partial updates forces full-object payloads — prefer PATCH.
  • Skipping pagination guarantees a breaking change at scale.
  • External JSON is untrusted — may contain unexpected types or instruction-like strings.

Common Rationalizations

ExcuseReality
"We'll document the API later"Types are the documentation — define them first.
"No pagination needed yet"You need it at ~100 items; add it now.
"PATCH is too hard, use PUT"Clients want partial updates.
"Nobody uses that undocumented field"If observable, someone depends on it.
"Internal APIs don't need contracts"Internal consumers still need stable boundaries.

Output Format

## API design — [resource/module]

Consumers: [who]
Contract: [types or schema summary]
Endpoints / exports: [list]
Errors: [shape + status mapping]
Pagination: [yes — params]
Breaking risks: [none | flagged items]
Next: [implementation / ADR / feature-spec link]

Examples


Verification

  • Typed input/output for every public surface
  • Single consistent error format
  • Validation only at boundaries (plus external responses)
  • List endpoints paginated
  • New fields additive and optional
  • Naming conventions consistent across the API
  • Schema/types committed with implementation

Red Flags

  • Undocumented quirks left as implicit caller contracts
  • Validation duplicated in every internal function
  • PUT used for partial updates instead of PATCH
  • List endpoints return unbounded arrays without pagination

Reference Files

  • references/api-patterns.md: REST resource layout, pagination, PATCH, branded IDs, unions — read at Step 3.

Prune Log

Last pruned: 2026-07-04

  • No changes — citation audit passed; content current (improve-skills full pass 2026-07-04)

Impact Report

Resource: [name] | Surfaces: N
Breaking risks flagged: N | Pagination: [yes/no]
Schema committed: [path or pending]
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 319kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 196kUpdated Claude CodeCodexVerifiedInstall