Reference Implementation

You have an OpenAPI spec and want a working, executable implementation that serves as the canonical example of how the API should behave — before the production service exists, or alongside it.

Problem

An OpenAPI spec describes the structure of an API but not its behavior. Teams building the production service, writing tests, or consuming the API have to interpret spec prose to understand what should happen in each situation. Misinterpretations accumulate silently until something breaks in production.

Solution

Implement every route handler in Counterfact to reflect the intended behavior of the API. TypeScript types derived from the spec make it impossible to return a response that violates the contract. The result is an executable, testable artifact that expresses the API’s behavior in code, not prose — and stays synchronized with the spec automatically.

Example

Write the OpenAPI spec, then generate and implement the handlers:

npx counterfact@latest openapi.yaml api

Implement each handler with the intended behavior:

// api/routes/pet.ts
export const POST: HTTP_POST = ($) => {
  if (!$.body.name) return $.response[400].text("name is required");
  const pet = $.context.add($.body);
  return $.response[200].json(pet);
};

TypeScript highlights contract violations in the IDE and in CI:

// Your IDE warns here if the response shape no longer matches the spec.
return $.response[200].json(pet);

When the spec changes, regenerate the types:

npx counterfact@latest openapi.yaml api --generate-types

TypeScript immediately surfaces every handler that no longer matches the updated contract. Fix those handlers, and the reference implementation is up to date.

Consequences