# API Contract Drift Audit

> Auditing client-server API contracts, schema parity, OpenAPI specifications, and tRPC/REST endpoints to prevent silent breaking changes. Use when frontend and backend contracts diverge, updating API versions, preparing deployments, or validating integration envelopes.

- Skill: `oyi77/api-contract-drift-audit` (Agent Skill)
- Install (CLI): `npx get-skill add oyi77/api-contract-drift-audit`
- Raw SKILL.md: https://api.skillmd.com/api/skills/oyi77/api-contract-drift-audit/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- License: Apache-2.0
- Author: oyi77 (https://skillmd.com/u/oyi77)
- Updated: 2026-11-12
- Page: https://skillmd.com/skills/oyi77/api-contract-drift-audit

---


## Overview

Distributed architectures and decoupled frontend/backend repositories break when server response schemas evolve without coordinated client updates. The API Contract Drift Audit playbook establishes automated contract verification across OpenAPI specs, tRPC routers, and REST envelopes, catching removed fields, altered data types, and changed status codes before deployment.

## Anti-Rationalization Table

| Rationalization | Engineering Reality | Strict Protocol |
|---|---|---|
| "Frontend and backend developers discussed the change in chat." | Verbal agreements do not prevent missed properties, typos, or forgotten client callers across web, mobile, and background jobs. | Schemas are the sole source of truth. Any wire modification must be verified against machine-readable OpenAPI or JSON schemas. |
| "Renaming a field is safe because we updated our web repository." | Mobile apps, cached browser tabs, external webhook listeners, and third-party API clients will immediately crash upon receiving undefined. | Treat all field renames as additions followed by deprecations. Provide dual-field support until legacy clients are decommissioned. |
| "A 200 OK status code means the contract is intact." | A 200 OK returning `{ data: null }` or `{ error: "auth" }` instead of `{ result: [] }` crashes downstream `.map()` calls without an HTTP error. | Assert the full JSON schema shape, required properties, and envelope structures, not just the HTTP status code. |
| "Making an optional field required is fine since the frontend always sends it." | Older mobile app versions, alternate platforms, or third-party webhooks may omit optional properties, resulting in sudden 422 errors. | Never turn an optional input field into a required one without introducing a new versioned endpoint or parameter. |
| "Manual Postman testing is enough before releasing API changes." | Manual testing checks a single happy path once; automated contract tests run continuously against mock and live environments on every PR. | Automate breaking change detection using CI contract diffing tools (e.g. `oasdiff`, `openapi-diff`, Prism). |
| "We don't need versioning for internal microservices." | Internal microservices deploy independently; rolling updates ensure old and new versions run concurrently in production. | Maintain backward compatibility on all internal endpoints or utilize versioned paths (`/v1/`, `/v2/`). |

## When to Use

- Monorepo or polyrepo architectures where frontend SPAs, mobile apps, and backend APIs are built by separate teams.
- Preparing to deploy schema modifications, route renames, or new required parameters to production endpoints.
- Establishing automated contract testing between microservices using OpenAPI, JSON Schema, or tRPC.
- Diagnosing production runtime exceptions like `TypeError: Cannot read property 'map' of undefined` on client apps.

## When NOT to Use

- Single-page monolithic web applications where frontend and backend are tightly compiled into one server-rendered binary.
- Purely internal database stored procedures or cron workers that do not expose external network interfaces.
- Greenfield development before the initial release where no external clients or production users exist.

## Workflow

```
┌────────────────────────────────────────────────────────┐
│             API Contract Drift Audit Workflow          │
└───────────────────────────┬────────────────────────────┘
                            │
                            ▼
┌────────────────────────────────────────────────────────┐
│ 1. Specification Snapshot & Ingress Extraction         │
│    - Export latest server OpenAPI / tRPC router spec   │
│    - Snapshot client-side interface expectations       │
└───────────────────────────┬────────────────────────────┘
                            │
                            ▼
┌────────────────────────────────────────────────────────┐
│ 2. Automated Schema Diff & Breaking Change Analysis    │
│    - Run diffing engine (oasdiff, openapi-diff)        │
│    - Flag removed properties, type changes, new errors │
└───────────────────────────┬────────────────────────────┘
                            │
                            ▼
┌────────────────────────────────────────────────────────┐
│ 3. Consumer-Driven Contract Verification               │
│    - Execute client mock tests against generated specs │
│    - Verify response envelope unwrapping safety        │
└───────────────────────────┬────────────────────────────┘
                            │
                            ▼
┌────────────────────────────────────────────────────────┐
│ 4. Defensive Envelope Shielding                        │
│    - Wrap client array mappers: data?.items ?? []      │
│    - Handle date parsing defensively (isNaN checks)    │
└───────────────────────────┬────────────────────────────┘
                            │
                            ▼
┌────────────────────────────────────────────────────────┐
│ 5. CI Gate Integration & Continuous Wire Verification   │
│    - Add breaking-change linter to backend PRs         │
│    - Reject unversioned breaking wire alterations      │
└───────────────────────────┘
```

### Step 1: Specification Snapshot & Ingress Extraction
Generate or export an accurate machine-readable schema for all exposed routes:
- **FastAPI**: Export `openapi.json` directly from the FastAPI application object.
- **Express / Fastify**: Generate OpenAPI spec via `@fastify/swagger` or `tsoa`.
- **tRPC**: Inspect router definition type signatures.

### Step 2: Automated Schema Diff & Breaking Change Analysis
Compare the newly generated schema against the production baseline:
- Use `oasdiff` or `openapi-diff` to categorize changes:
  - **Non-breaking**: Added optional field, added new endpoint.
  - **Breaking**: Removed field, changed type (string -> number), added required request parameter, changed status code.

### Step 3: Consumer-Driven Contract Verification
Validate client consumption against the server schema:
- Use mock servers (e.g. Prism) seeded with the server's OpenAPI specification.
- Run client-side integration test suites against the Prism mock to detect wire mismatch.

### Step 4: Defensive Envelope Shielding
Harden client consumers against unexpected wire payloads:
- Defensive list unpacking: `const items = Array.isArray(res.data) ? res.data : res.data?.items ?? [];`
- Defensive date parsing: `const date = new Date(raw); const safeDate = isNaN(date.getTime()) ? null : date;`

### Step 5: CI Gate Integration & Continuous Wire Verification
Add a breaking-change validation step to the CI pipeline:
- Fetch baseline schema from the `main` branch.
- Diff against the feature branch schema; fail the build if breaking changes are detected without an explicit deprecation tag.

## Code Examples

### Automated OpenAPI Breaking Change Detection Script (`scripts/check-api-drift.py`)

```python
import json
import sys
import urllib.request
from pathlib import Path

def fetch_or_read_json(source: str) -> dict:
    if source.startswith("http://") or source.startswith("https://"):
        req = urllib.request.Request(source, headers={"User-Agent": "1ai-contract-audit"})
        with urllib.request.urlopen(req) as resp:
            return json.loads(resp.read().decode("utf-8"))
    return json.loads(Path(source).read_text(encoding="utf-8"))

def detect_breaking_changes(baseline_spec: dict, current_spec: dict) -> list[str]:
    breaking = []
    base_paths = baseline_spec.get("paths", {})
    curr_paths = current_spec.get("paths", {})

    for path, methods in base_paths.items():
        if path not in curr_paths:
            breaking.append(f"[REMOVED ENDPOINT] Route '{path}' was removed.")
            continue

        for method, details in methods.items():
            if method not in curr_paths[path]:
                breaking.append(f"[REMOVED METHOD] Method '{method.upper()}' on '{path}' was removed.")
                continue

            base_responses = details.get("responses", {})
            curr_responses = curr_paths[path][method].get("responses", {})

            for status in base_responses:
                if status not in curr_responses:
                    breaking.append(f"[REMOVED STATUS] Expected status '{status}' on {method.upper()} {path} missing.")

    return breaking

if __name__ == "__main__":
    if len(sys.argv) < 3:
        print("Usage: python check-api-drift.py <baseline_spec.json> <current_spec.json>")
        sys.exit(1)

    base = fetch_or_read_json(sys.argv[1])
    curr = fetch_or_read_json(sys.argv[2])
    issues = detect_breaking_changes(base, curr)

    if issues:
        print(f"FAILED: {len(issues)} breaking API contract changes detected:")
        for issue in issues:
            print(f"  {issue}")
        sys.exit(1)

    print("SUCCESS: Zero breaking API contract changes detected.")
```

### Defensive Client-Side Envelope Shield (TypeScript)

```typescript
export interface ApiResponseEnvelope<T> {
  data?: T | null;
  items?: T[];
  error?: { message: string; code: string } | null;
  success?: boolean;
}

export function defensivelyUnpackList<T>(response: unknown): T[] {
  if (!response || typeof response !== 'object') {
    return [];
  }

  const envelope = response as ApiResponseEnvelope<T>;

  // Case 1: Bare array response
  if (Array.isArray(response)) {
    return response as T[];
  }

  // Case 2: data is an array
  if (Array.isArray(envelope.data)) {
    return envelope.data;
  }

  // Case 3: items array inside envelope
  if (Array.isArray(envelope.items)) {
    return envelope.items;
  }

  // Case 4: Malformed or empty envelope
  return [];
}

export function parseWireDate(rawDate: unknown): Date | null {
  if (typeof rawDate !== 'string' && typeof rawDate !== 'number') {
    return null;
  }
  const parsed = new Date(rawDate);
  return isNaN(parsed.getTime()) ? null : parsed;
}
```

### End-to-End Contract Integration Test (Vitest / Supertest)

```typescript
import { describe, it, expect } from 'vitest';
import request from 'supertest';
import { app } from '../src/app';

describe('API Contract Wire Parity: /api/v1/users', () => {
  it('returns valid UserEnvelope matching OpenAPI specification', async () => {
    const res = await request(app)
      .get('/api/v1/users')
      .expect(200);

    expect(res.headers['content-type']).toMatch(/json/);
    expect(res.body).toHaveProperty('success', true);
    expect(Array.isArray(res.body.data)).toBe(true);

    if (res.body.data.length > 0) {
      const user = res.body.data[0];
      // Assert critical contract fields required by client
      expect(user).toHaveProperty('id');
      expect(typeof user.id).toBe('string');
      expect(user).toHaveProperty('email');
      expect(typeof user.email).toBe('string');
      expect(user).toHaveProperty('role');
    }
  });
});
```

## Verification Checklist

- [ ] Up-to-date OpenAPI / JSON schema specification generated from backend source.
- [ ] Schema diff run between baseline branch and feature branch with zero unversioned breaking changes.
- [ ] No required fields added to existing request schemas without backwards-compatible defaults.
- [ ] No fields removed or renamed from response payloads without a formal deprecation period.
- [ ] Client applications implement defensive envelope unpackers (`data?.items ?? []`).
- [ ] Contract test suite executes against live or mock API server and passes 100%.

