Skip to content

executable-spec.md

Latest commit

 

History

History
67 lines (50 loc) · 3.01 KB

executable-spec.md

File metadata and controls

67 lines (50 loc) · 3.01 KB

Executable Spec

You are designing an API and want immediate feedback on how each change to the spec affects the behavior of the running server and the clients that depend on it.

Problem

API design happens in a document — the OpenAPI spec — while the feedback comes much later, when clients are built and integrated. By then, mistakes in the spec are expensive to fix.

Solution

Run Counterfact with --watch while authoring the spec. Every time you save the spec, types regenerate and the server reflects the updated contract instantly. You can send real requests to observe how a spec change would behave, and TypeScript surfaces any handler that no longer matches the updated contract — while the server is still running.

Example

Start with a spec for a pet clinic API and run Counterfact in watch mode:

npx counterfact@latest openapi.yaml api --watch

Now add a new Vaccination component to the spec and attach vaccination records to the Pet schema:

components:
  schemas:
    Vaccination:
      type: object
      properties:
        vaccine:
          type: string
        date:
          type: string
          format: date
    Pet:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        vaccinations:
          type: array
          items:
            $ref: "#/components/schemas/Vaccination"

Save the file. Counterfact regenerates the types immediately. The GET /pet/{petId} handler's return type now includes vaccinations. If the handler uses the default random() implementation, the server already returns the new field automatically:

⬣> client.get("/pet/1")
{ status: 200, body: { id: 1, name: 'Fluffy', vaccinations: [{ vaccine: 'Rabies', date: '2024-03-15' }] } }

If the handler returns a fixed value, you will need to update it — but TypeScript guides you: the IDE highlights the mismatch and describes exactly what is missing or incorrect. You can iterate on the spec — adding fields, changing types, restructuring schemas — and see the downstream effects on handlers and responses before any client code is written.

Consequences

  • Feedback on spec changes is instantaneous: save the spec, observe the effect on the running server.
  • Type warnings appear in the IDE when handlers no longer match the updated contract; the server keeps running during the transition.
  • The pattern works best during early API design, when the spec is still fluid and the cost of mistakes is low.
  • Handlers must be updated manually to produce semantically correct responses after spec changes; type checking only catches structural mismatches.

Related Patterns