api-and-interface-design

API And Interface Design

Overview

API And Interface Design turns a proposed API, SDK, event, CLI, component prop surface, or service boundary into an explicit contract before code hardens it. It keeps Supervibe memory, CodeGraph, source evidence, receipts, and verification in the workflow while adding one consumer-first interface pass.

Use it to decide shape, compatibility, errors, idempotency, pagination, authorization declaration, versioning, examples, and observability before implementation or review.

When to Use

Use before adding or changing a public or cross-team interface. Use when a spec, schema, endpoint, event, SDK method, CLI command, plugin config, or component contract may be consumed by code outside the edited module. Use before supervibe:error-envelope-design or supervibe:auth-flow-design when the broader interface shape is still undecided.

Expert Operating Standard

Follow <resolved-supervibe-plugin-root>/docs/references/skill-expert-operating-standard.md: start from source of truth, preserve context evidence, apply scope safety, use real producers with runtime receipts for durable delegated outputs, verify before completion claims, and keep confidence below gate when evidence is partial.

Step 0 - Read source of truth

1. Read AGENTS.md, the active requirement/spec/PRD, and any existing API or interface convention docs.
2. Search project memory for prior versioning, error envelope, auth, pagination, SDK, or plugin contract decisions.
3. Run CodeGraph for existing interface patterns and read the top relevant files before designing a new shape.
4. Use CodeGraph before changing an exported symbol, generated client surface, command argument, event name, or public schema. 4a. Identify existing consumers and the currently working request/response, event, SDK, CLI, or component behavior that must remain compatible.
5. If the interface depends on external standards or provider behavior, invoke supervibe:source-driven-development and prefer official current docs.

Anti-patterns

• Ignoring the boundary: Do not use for purely internal implementation details with no observable consumer contract.
• Accepting the rationalization: "It is internal, so compatibility does not matter" fails when another module, generated client, task runner, or plugin can observe the shape.
• Proceeding despite this red flag: Request/response shape is inferred from code instead of written as a contract.
• Letting the known failure mode happen: Interface design mirrors database schema and leaks internal coupling.

When not to use

• Do not use for purely internal implementation details with no observable consumer contract.
• Do not use to bypass supervibe:error-envelope-design, supervibe:auth-flow-design, supervibe:deprecation-and-migration, or formal API reviewers when those narrower gates apply.
• Do not approve a breaking change without a migration path, versioning decision, and release owner.

Decision tree

Is the surface observable outside the edited module?
  NO  -> use local implementation skills and keep this skill out of scope.
  YES -> continue.

Is the change additive and backward compatible?
  YES -> document the contract, examples, tests, and changelog decision.
  NO  -> require versioning, deprecation, migration, rollback, and consumer impact.

Does the surface mutate state or trigger side effects?
  YES -> require idempotency, retry semantics, auditability, and auth declaration.
  NO  -> require pagination/filtering/sorting semantics when collections are involved.

Practice matrix

Surface	Must decide	Evidence to capture
HTTP/JSON endpoint	method, status codes, problem+json errors, pagination, idempotency	OpenAPI diff, success/error examples, contract test command
GraphQL operation	query/mutation shape, nullable fields, union/error pattern, deprecation	schema diff, resolver caller check, client query fixture
SDK or CLI	stable method/flag names, exit/error semantics, generated docs	generated client diff, backwards-compatible example, changelog
Event/webhook	schema version, replay behavior, signing, retry window	fixture payloads, signature verification, consumer list

Procedure

1. Read existing conventions and identify consumers: browser, mobile, service, SDK, plugin host, CLI user, webhook receiver, or internal worker.
2. Define the operation list and name each operation from the consumer's perspective, not from storage tables or internal classes.
3. Write request, response, event, or method shapes with required/optional fields, nullable values, defaults, and unknown-field behavior.
4. Define errors using the project canonical envelope; if none exists, invoke supervibe:error-envelope-design.
5. Define auth/authz declaration; if unclear, invoke supervibe:auth-flow-design.
6. Define idempotency and retry behavior for every mutation, webhook, queue handler, or command with external side effects.
7. Define collection semantics: cursor or page model, sort order, filters, max page size, and stable empty response.
8. Define compatibility rules: additive changes, deprecations, breaking changes, generated client impact, versioning scheme, and sunset window. Fresh docs or cleaner interface patterns do not override compatibility with current consumers.
9. Add examples for success, validation failure, auth failure, rate limiting, empty collection, and retry/idempotency when relevant.
10. Name contract tests, schema diff checks, or static validators that will prove the interface stays stable.
11. Record observability: request id, correlation id, audit log, metrics, and alert hooks needed to support the interface.
12. Score with supervibe:confidence-scoring; do not mark complete below the gate.
13. Workflow cycle: read source and consumers -> produce the contract -> run or name the scoped verification -> if verification fails, consumers are unknown, or compatibility is disputed, repair the contract and rerun the same command before handoff.

Common rationalizations

• "It is internal, so compatibility does not matter" fails when another module, generated client, task runner, or plugin can observe the shape.
• "We can add versioning later" fails because first consumers turn today's defaults into tomorrow's compatibility contract.
• "The implementation is obvious" fails when errors, retries, auth, pagination, or null handling are not specified.

Red flags

• Request/response shape is inferred from code instead of written as a contract.
• Mutation lacks idempotency or retry semantics.
• Error examples differ by endpoint, event, or transport without a recorded reason.
• A field rename, enum narrowing, status-code change, or auth-scheme change is called non-breaking without consumer evidence.
• A new best-practice interface replaces a working contract without an additive path, version, deprecation, or compatibility bridge.
• Generated clients, SDKs, webhooks, or docs are not mentioned in verification.

Checklist

• Consumers and compatibility class are named.
• Shape, errors, auth, idempotency, pagination, versioning, and examples are explicit.
• Consumer-impact and generated-client impact are checked.
• Contract tests, schema diff, or lint commands are named.
• Rollback, deprecation, and changelog decisions are recorded when needed.

Failure modes

• Interface design mirrors database schema and leaks internal coupling.
• One happy-path example hides validation, auth, empty, and retry behavior.
• Public behavior changes without a version bump, deprecation window, or migration guide.
• The skill emits prose but no testable contract fields.

Examples

• Good example: POST /billing/exports returns 202 with {id,status,createdAt}, accepts Idempotency-Key, uses billing.export_already_running from the registry, and names node --test tests/billing-export-contract.test.mjs plus an OpenAPI diff before handoff.
• Good example: order.shipped.v2 keeps deprecated carrierName for one major version, adds optional trackingUrl, includes a webhook replay fixture, and records consumer owners before release.
• Anti-example: renaming userId to accountId in an SDK method and calling it additive because the API still accepts both fields; generated clients and caller code observe the method signature, so this needs migration evidence.

Output contract

Return parseable apiInterfaceContract:

• status: PASS, PARTIAL, or BLOCKED.
• surface: endpoint, SDK method, event, CLI, config, component, or service boundary.
• consumers: known consumer classes and unknown-consumer risk.
• contract: request/response/event/method shape with required, optional, nullable, default, and unknown-field behavior.
• semantics: auth, errors, idempotency, pagination, rate limits, retries, ordering, and observability.
• compatibility: additive/deprecating/breaking classification with versioning and migration plan when needed.
• examples: success and failure examples.
• verificationCommands: exact contract lint, diff, test, or grep commands.
• evidence: source files, CodeGraph refs, schema diffs, fixtures, receipts, or manual inspection notes.
• confidence: score and cap reason when degraded.
• blockers: missing consumers, missing canonical envelope/auth decision, or unavailable contract proof.
• nextAction: repair, rerun, owner handoff, or release-gate command.
• residualRisk: open consumer or tooling uncertainty.

Guard rails

• Do not claim backward compatibility without consumer-impact evidence.
• Do not design a new error or auth convention when a local canonical skill owns it.
• Do not change generated or public surfaces without CodeGraph or explicit Case C rationale.
• Preserve host-neutral wording and avoid provider-specific folders unless the artifact is adapter-specific.

Verification

• npm run validate:skill-content-quality
• Run the relevant interface validator when a concrete artifact exists, such as spectral lint, oasdiff, graphql-inspector diff, buf breaking, schema tests, or project-specific contract tests.
• For repository changes, run the targeted validator named by the owning agent or plan.
• After any repair, rerun the same contract diff/test command and record exit code, changed artifact path, and remaining blockers before claiming the interface is ready.

Supporting references

Use local support files through progressive disclosure; keep the main SKILL.md as the operating contract and load deeper resources only when the active task needs them:

• Read references/practice-pack.md when api-and-interface-design needs deeper practice guidance, source evidence anchors, risk checks, or a final checklist beyond the core procedure.
• Run scripts/self-check.mjs --check --json after editing this api-and-interface-design resource tree or before claiming deterministic support-file readiness; use --help for options and --dry-run for read-only preview semantics.
• Use evals/regression.json when calibrating api-and-interface-design trigger boundaries, happy-path/failure-path coverage, boundary rollback behavior, or resource-tree regressions.
• Open examples/workflow.md when a concrete api-and-interface-design workflow example is needed for sequencing, evidence selection, or anti-example comparison.
• Use templates/output-contract.md when emitting api-interface-contract so status, evidence, confidence, blockers, risks, rollback, and nextAction stay consistent.

Related

• supervibe:error-envelope-design
• supervibe:auth-flow-design
• supervibe:deprecation-and-migration
• supervibe:documentation-and-adrs
• supervibe:source-driven-development