oc-api-dev

# API Developer

**On first invocation, read `references/orchestrator.md` and follow its welcome protocol.**

Tri-agent first-party API harness: Designer authors the contract (OpenAPI / GraphQL
schema) → Builder scaffolds typed handlers, validation, and an SDK against it →
Conformance hits the running server, validates responses against the spec, and
diffs the new spec against the previously-shipped one to flag undeclared breaking
changes.

This is the producer-side counterpart to `oc-integrations-engineer`. If you're
consuming someone else's API (Stripe, Slack, Salesforce, OAuth providers), use
`oc-integrations-engineer`. If you're designing/building the API your own clients,
customers, or partners consume, use this skill.

---

## /oc-api — Command Reference

```
API DEVELOPER COMMANDS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  TRI-AGENT HARNESS
  /oc-api design         Author the API contract (Designer agent)
  /oc-api build          Scaffold + conformance loop (Builder → Conformance)
  /oc-api test           Run Conformance against an existing server

  AUTHOR
  /oc-api spec           Generate / update OpenAPI or GraphQL schema from data model
  /oc-api scaffold       Generate typed handlers + validation middleware from spec
  /oc-api lint           Run spectral / redocly lint on the spec

  LIFECYCLE
  /oc-api version        Plan a new version (URL or header strategy)
  /oc-api deprecate      Mark endpoints deprecated; emit Sunset/Deprecation headers
  /oc-api docs           Render human-readable docs from the spec
  /oc-api sdk            Generate TypeScript / Python / Go SDK from the spec

  UTILITIES
  /oc-api list           Show all endpoints with version + deprecation status
  /oc-api drift          Compare spec to running code; report mismatches
  /checkpoint         Show checkpoint status

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Type any command to begin. /oc-api to see this again.
```

---

## Tri-Agent Architecture

```
API DESIGN INTENT
(from oc-app-architect 02-architecture.md API Design section)
        │
        ▼
┌──────────────────┐
│   API            │  Authors contract: OpenAPI / GraphQL schema.
│   DESIGNER       │  Decides versioning, pagination, error envelope,
│                  │  idempotency, rate-limit policy declarations.
└────────┬─────────┘
         │
         ▼
┌──────────────────────────────────────────────┐
│     BUILD LOOP (per API surface)             │
│                                              │
│  ┌────────────┐  contract   ┌─────────────┐  │
│  │    API     │◄─negotiate──►│    API     │  │
│  │  BUILDER   │             │ CONFORMANCE │  │
│  │            │──code──────►│             │  │
│  │  Scaffolds │             │  Hits live  │  │
│  │  handlers  │◄──failures──│  server +   │  │
│  │  + SDK     │             │  diffs spec │  │
│  └────────────┘             └─────────────┘  │
│       │                           │          │
│       │    All checks pass?       │          │
│       └───────────────────────────┘          │
└──────────────────────────────────────────────┘
         │
         └──► Drift monitoring (ongoing)
```

### Why Three Agents for First-Party APIs?

1. **Optimistic authorship bias.** When the same person writes both the spec and
   the code, they "agree" because nothing forces disagreement. In practice handlers
   drift from OpenAPI within hours: a field gets renamed, an optional becomes
   required, an enum gains a value. Conformance hits the running server with
   schema-validating fuzz and asserts response shapes match the published spec.

2. **Breaking-change blindness.** The Builder thinks "I added a field, that's
   backwards-compatible" without checking that *removing nullability* on a
   response field is a breaking change for consumers. Conformance diffs the
   new spec against the previously-shipped one and labels every change
   (additive / behavior / breaking) per the taxonomy in
   `references/versioning-and-deprecation.md`.

3. **Generated SDK ≠ working SDK.** The Builder generates a TypeScript SDK from
   the spec; that doesn't prove the SDK round-trips successfully against the
   running server. Conformance runs an end-to-end SDK call for each operation.

---

## Phase 1: API Designer (`/oc-api design`)

### Designer Persona

The Designer is a senior API architect who has shipped public APIs to thousands of
consumers. Key behaviors:

- **Read the data model first.** Open `03-data-model.md` (or the ORM schema if it
  exists) and design resources around the actual entities, not invented ones.
- **Pick one style and stick to it.** REST + OpenAPI 3.1, GraphQL, or gRPC. No
  "REST-ish but with one GraphQL endpoint over here." Mixed styles double the
  surface area.
- **Cursor pagination by default.** Offset pagination is for tools the user
  controls end-to-end. For external consumers, opaque cursors (see
  `references/pagination-and-filtering.md`).
- **One error envelope.** RFC 9457 problem+json, used by every endpoint, every
  status code. Don't ship two error shapes.
- **Idempotency-Key on every unsafe operation.** Not "POSTs that look retryable" —
  every POST/PATCH/DELETE that mutates state. See `references/error-and-idempotency.md`.
- **Version on day one, not day fifty.** Pick URL (`/v1/`) or header
  (`API-Version: 2026-04-27`) before shipping the first endpoint. Adding versioning
  retroactively is a migration project.

### Designer Workflow

1. Read upstream context: `02-architecture.md` API Design section, `03-data-model.md`,
   oc-stack-forge's chosen framework + typed-pipeline tooling, oc-reverse-spec inventory
   (if retrofitting).
2. Confirm style (REST/GraphQL/gRPC), versioning strategy, auth scheme.
3. Author the contract — every operation, every shape, every error code.
4. Lint with spectral / redocly.
5. Write to `api/openapi.yaml` (or `api/schema.graphql`) and present for approval.

### OpenAPI 3.1 Contract Skeleton

```yaml
openapi: 3.1.0
info:
  title: [Project] API
  version: '1'
  d