Skip to content

API-First Design

Design the API before you write a single line of implementation code. The OpenAPI specification is the contract. Everything else follows from it.

Why API-First Exists

Traditional development builds the API as a byproduct of the implementation. The database schema comes first, then the ORM, then whatever endpoints the backend developer decides to expose. The frontend team discovers the API shape when the pull request lands. Mismatches surface in integration. Rework follows.

API-first inverts this. The interface is designed collaboratively, agreed upon, and version-controlled before any implementation begins. The spec becomes the single source of truth (SSOT) for:

  • Request and response shapes
  • Validation rules
  • Authentication requirements
  • Error formats
  • Pagination contracts
  • Versioning boundaries

Why API-First Matters for Agentic Development

In a 60-agent system like GE, API-first is not a preference — it is a structural requirement. Here is why:

Agents can generate client code from the spec

When Anna (Formal Specification Agent) produces an OpenAPI document, every downstream agent — backend, frontend, test — can generate type-safe clients automatically. No Slack thread asking "what does the response look like?" No guessing at field names.

Agents can test against the spec

Antje (Test Agent) and Koen (Code Quality Automation) can generate contract tests directly from the OpenAPI document. If the implementation drifts from the spec, CI catches it before any human reviews the PR.

Agents can validate against the spec

Jaap (SSOT Enforcer) uses the spec as ground truth. If a handler returns a field not in the spec, or omits a required field, it is a spec violation — not a judgment call.

Parallel development becomes real

With a stable spec, frontend and backend agents work simultaneously. Mock servers generated from the spec let UI development proceed without waiting for a working backend.

Onboarding new agents is instant

A new agent joining a project reads the OpenAPI spec and immediately understands every endpoint, every type, every error. No tribal knowledge required.

GE Convention: Hono + Zod + OpenAPI

GE uses a specific toolchain for API-first development:

Hono

The web framework. Lightweight, edge-ready, TypeScript-native. Runs on Node, Deno, Bun, Cloudflare Workers, and more.

Zod

The validation library. Defines schemas once, used for:

  • Runtime validation (request bodies, query params, path params)
  • TypeScript type inference (no separate type definitions)
  • OpenAPI schema generation (via @hono/zod-openapi or hono-openapi)

With Zod v4, use .issues not .errors on ZodError. Use .meta({ ref: "..." }) to register schemas as reusable #/components/schemas/ references in the OpenAPI document.

@hono/zod-openapi

The integration layer. Extends the Hono class to support OpenAPI route definitions with Zod schemas. A single route definition provides:

  • Runtime request validation
  • Response type checking
  • Automatic OpenAPI document generation
  • RPC-mode type inference for Hono Client

The workflow

1. Anna writes functional spec → includes API contract
2. Dev agent defines Zod schemas for all request/response types
3. Dev agent defines OpenAPI routes using @hono/zod-openapi
4. OpenAPI document auto-generates from route definitions
5. Antje generates contract tests from the OpenAPI document
6. Koen validates implementation matches spec in CI
7. Jaap enforces spec as SSOT — no drift allowed

Spec-First, Not Code-First

The spec must exist before the implementation. This means:

  1. Anna produces the API contract as part of the formal specification
  2. The team reviews the contract — endpoint names, shapes, errors
  3. The contract is version-controlled in the project repository
  4. Implementation follows the contract — not the other way around
  5. Drift is a CI failure — not a cleanup task

If the implementation needs to diverge from the spec, the spec is updated first through a formal change process. The spec leads. The code follows.

What the Spec Must Include

Every OpenAPI document in GE must define:

  • All endpoints with method, path, and operation ID
  • Request schemas for body, query, path, and header parameters
  • Response schemas for every status code the endpoint can return
  • Error responses in RFC 9457 Problem Details format
  • Authentication requirements per endpoint
  • Pagination parameters for list endpoints
  • Rate limit headers in response schemas
  • Examples for at least the happy path

Ownership

Role Agent Responsibility
Backend Team Lead (Alfa) Urszula API design review, convention enforcement
Backend Team Lead (Bravo) Maxim API design review, convention enforcement
Formal Specification Anna API contract as part of spec
Code Quality Koen Spec-implementation drift detection in CI
SSOT Enforcer Jaap Spec is ground truth — no exceptions

Key Principle

The OpenAPI specification is not documentation. It is the contract. Break the contract, break the build.

Further Reading