Catch a breaking API change before your users do

Task

A vendor can rename or drop a field without telling you, and a plain type check will not notice until something breaks in production. You want to be warned the moment the response shape moves — and to triage it by severity, not panic on every change.

Example

One way: wrap the output schema with drift and a committed baseline.

import { drift, stitch } from 'stitchapi';
import { z } from 'zod';

const getUser = stitch({
    baseUrl: 'https://api.example.com',
    path: '/users/{id}',
    output: drift(z.object({ id: z.number(), email: z.string() }), {
        critical: ['id'],
        watch: ['email'],
        snapshotFile: 'users.contract.json',
    }),
});

const user = await getUser({ params: { id: 1 } });

How it works

The first call records the baseline into users.contract.json (check it into the repo); every call after compares the response and emits leveled findings. critical paths change at level error — that breaks the contract and throws STITCH_DRIFT. watch paths change at warn, and brand-new fields default to info (onNew). warn and info findings do not throw — they ride the event stream as drift events, so you can watch a field erode before it breaks. This is the opposite end from plain validation, which rejects one malformed response hard, here and now.

See also