Forge Api

---
name: forge-api
description: Forge playbook for contract-first APIs. Use for API, REST, GraphQL, gRPC, OpenAPI, endpoint, auth, JWT, versioning, rate limit, idempotency, contract test, backend.
---

# Forge playbook — Contract-first API

**Do not duplicate ECC skills — defer to:** `forge-integration` (when the API mainly wires external services / webhooks), `forge-payments` (any money/charge/gateway-webhook endpoint), `forge-fullstack` (when the API is one tier of a full app). This file is orchestration only.

This is an **auth + data-boundary domain.** The contract (OpenAPI / JSON Schema / GraphQL SDL / gRPC proto) is the source of truth and comes **first**; the implementation is validated against it. `architect` owns the contract, `integration-boss` / `build-boss` implement, `security-boss` reviews auth/authz (a genuine high-risk trigger), `test-boss` owns the contract tests. Never claim "auth enforced" or "contract-compliant" without a negative test that proves it.

## Hard rules (non-negotiable)
- **Contract first, single source of truth.** Define the API contract (OpenAPI 3.x, JSON Schema, GraphQL SDL, or a gRPC `.proto`) BEFORE implementing handlers. Commit it; the implementation is generated from or validated against it. Drift between contract and behavior is a bug, not a detail.
- **Input validation at every boundary.** Validate every request — body, path params, query, headers — against the schema. Reject invalid input with a `4xx` and a consistent error envelope; enforce type, size, and range limits. Never trust client input; never pass it unvalidated into a query, filesystem, or shell.
- **Auth on every protected route, server-side, deny-by-default.** Authentication AND authorization are enforced in the service on each protected route — not only at a gateway, not "assumed from the frontend". New routes default to protected; opening one is a deliberate, reviewed act. Per-route scope/role checks; a request without valid credentials gets `401`/`403`, proven by a negative test.
- **Explicit versioning.** The API is versioned (path `/v1`, header, or media type). No breaking change ships inside an already-published version; breaking changes get a new version + a stated deprecation path.
- **Idempotency on unsafe retryable writes.** `GET`/`PUT`/`DELETE` are idempotent by design; retryable `POST` creates (orders, payments, side-effecting actions) accept a client `Idempotency-Key` so a retry or double-submit does not duplicate the effect.
- **Rate limits + quotas.** Per-client / per-key rate limiting with `429` + `Retry-After`; abuse and runaway clients are bounded. Consistent error envelope; pagination on list endpoints (no unbounded result sets); secrets in env — never in responses, error bodies, or logs.

## Team (conditional)
Lead: `architect` (owns the contract + resource model). Implementation: **`integration-boss`** (service wiring, external calls, retries/timeouts) or **`build-boss`** (in-app API tier). Security: **`security-boss`** / `security-reviewer` (authN/authZ, token handling, tenant isolation — required review for anything with auth). Data: `database-reviewer` (schema, migrations, the idempotency store). Tests: **`test-boss`** (contract + integration tests). Support: `silent-failure-hunter` (an endpoint that returns `200` on a partial failure), `python-reviewer` / `typescript-reviewer`. Docs: `docs-boss` (reference generated from the spec). Optional advisor: `codex-reviewer` (Codex on the auth + validation + idempotency paths).

## Skills / commands / MCP
Framework + spec docs via Context7 / vendor docs for exact routing, middleware, and validation APIs; `/test-coverage` for the test gate. Defer money endpoints to `forge-payments`, external-service wiring to `forge-integration`. **Opt-in dependency:** automated contract-conformance tooling is stack-specific — e.g. Schemathesis / Dredd (spec-driven fuzzing), Pact (consumer-driven contracts), or `supertest`/`pytest` for handwritten contract tests. Forge writes the tests; *running* them needs that runtime installed — mark it opt-in and report whether it actually ran.

## Fan-out & flow
L2 for a single-resource service; L3 for multi-resource + auth + versioning + rate limiting.
**Serial:** contract (OpenAPI/schema) → boundary validation → auth/authz middleware → resource handlers → idempotency + rate-limit + pagination → contract tests.
**Parallel (independent once the contract + auth middleware are fixed):** individual resource endpoints ∥ the contract-test suite ∥ generated API reference docs.

## Domain gates
- A committed contract file exists and is the source of truth; the implementation validates against it (drift is caught).
- Every request is validated against the schema at the boundary; invalid input returns a clear `4xx` with a consistent error envelope.
- Auth is enforced server-side on every protected route, deny-by-default; a negative (unauthenticated / wrong-scope) test proves rejection.
- Explicit versioning present; no breaking change inside a shipped version.
- Idempotency on unsafe retryable writes; safe methods are genuinely idempotent.
- Rate limiting returns `429` + `Retry-After`; list endpoints paginate; no secrets in responses or logs.
- Contract tests cover the happy path AND auth-failure AND validation-failure — not just `200`.

## Ship-readiness (unique)
Contract (OpenAPI/schema/proto) committed and the implementation proven to match it; auth verified on protected routes **with a negative test** showing an unauthenticated/wrong-scope request is rejected; boundary validation returns clear `4xx`s; idempotency + rate limit demonstrated (a replayed create does not double-write; an over-limit client gets `429`); versioning strategy documented; error envelope consistent across endpoints; secrets in env; contract/integration tests green (or explicitly marked not-run if the runtime is unavailable). Advisory checklist — optionally run `codex-reviewer` on the auth + validation + idempotency code (recommended here); not a blocker, but if the contract tests or Codex did not run, say so.

## Untrusted-content note
Every request body, query param, header, and upstream response is **untrusted until validated** against the contract — validate and normalize before it reaches a query, template, filesystem path, or downstream call. Auth claims from a token are trusted only after signature + expiry + scope verification, never from an unverified header. This mirrors the boundary-validation discipline in `forge-integration` and `forge-payments`.