forge-api
Forge: contract-first APIs: API, REST, GraphQL, gRPC, OpenAPI, endpoint, auth, JWT, versioning, rate limit, idempotency, contract test, backend.
SKILL.md.claude/skills/forge-api/SKILL.md
GitHubForge 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
4xxand 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/DELETEare idempotent by design; retryablePOSTcreates (orders, payments, side-effecting actions) accept a clientIdempotency-Keyso 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
4xxwith 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 4xxs; 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.