---
name: loom-api-and-interface-design
description: "Use when a shared interface needs consumer, compatibility, error, permission, or migration design before implementation, including REST, GraphQL, CLI, event, module, component, file-format, packet, worker, or cross-system contracts."
---

# loom-api-and-interface-design

API and interface design is a spec-first playbook for shared contracts.

It defines the contract before implementation, checks compatibility and error
semantics, and routes execution through tickets, evidence, and audit.

## Core Dependency

Use `loom-core` first. This playbook composes `loom-specs`, `loom-research`,
`loom-tickets`, `loom-evidence`, `loom-audit`, `loom-constitution`, and
`loom-knowledge`.

## Use This Playbook When

Use this playbook when designing or changing:

- REST, GraphQL, RPC, event, webhook, or CLI interfaces
- module boundaries or exported functions
- component props or design-system contracts
- data shapes, file formats, records, packets, or worker handoffs
- frontend/backend contracts
- public behavior that consumers may depend on

## Route

Use this route:

```text
consumer -> contract -> compatibility -> implement -> evidence -> audit
```

## Consumer

Identify the consumers:

- users, callers, clients, components, services, workers, agents, or future records
- existing consumers and their current assumptions
- compatibility expectations
- unsupported consumers and non-goals

Inspect current code, docs, specs, tests, and usage before changing an interface.

## Contract

Write or update a `loom-specs` record when the interface is durable.

Cover:

- inputs and validation boundary
- outputs and generated fields
- side effects
- idempotency
- ordering and pagination
- error semantics
- permission and authentication behavior
- compatibility and deprecation expectations
- observability or event emission
- examples and non-examples
- `REQ-*` and `SCN-*` IDs for downstream tickets and audit

## Compatibility

Prefer additive changes when existing consumers depend on the interface.

Check:

- field removal or type changes
- renamed enum values
- changed nullability
- changed ordering, pagination, or default limits
- error code and status changes
- timing or retry semantics
- undocumented behavior known to be used

Route policy or compatibility precedent to `loom-constitution` when it should guide
future interface changes.

## Implement

Use `loom-tickets` and `loom-ralph` for scoped implementation.

Implementation guidance:

- validate untrusted input at system boundaries
- keep internal contracts typed and simple
- separate input and output types when generated fields or sanitized output matter
- use consistent error shape across related endpoints
- document public behavior in the spec or source docs that consumers actually use
- add tests at the contract boundary

## Evidence And Audit

Evidence should show the interface contract works:

- contract tests
- request/response examples
- schema validation output
- generated docs
- migration or compatibility checks
- consumer integration checks

Use audit for public or high-risk interface changes, especially compatibility,
auth, permission, security, migration, or data-shape changes.

## Done Means

The interface pass is done when:

- the contract is captured in specs or a scoped ticket
- consumers and compatibility risks are named
- implementation tests or observations support the scenarios
- docs or examples match actual behavior
- breaking changes have migration or deprecation follow-up
- audit or review is complete for high-risk surfaces