How to Detect API Drift Before Your Customers Do

What is API drift?

API drift happens when the behavior your API actually exhibits diverges from what your documentation says it does. This manifests in several ways:

• A parameter is renamed in code but not in docs (user_id → userId)
• A field becomes required but docs show it as optional
• A response shape changes (new field added, old field removed)
• An endpoint is deprecated but docs show it as current
• Auth requirements change (e.g., new scope required)

The dangerous thing about drift is that it's asymmetric: it's easy to create and hard to notice. A single engineer makes a one-line change to the API contract. No alarm fires. The documentation stays wrong for weeks or months until a developer stumbles into the mismatch.

The three layers of API drift detection

DocsCI's drift detection works at three layers, which together cover the vast majority of real-world drift patterns:

# OpenAPI spec says:
POST /users
  required: [email, plan]  ← plan is required

# Docs say:
POST /users
  required: [email]        ← drift: plan not documented as required

# Docs example:
curl -X POST https://api.example.com/users \
  -d '{"email":"user@example.com"}'
# Expected: 201
# Actual: 422 (missing required field 'plan')
# → DRIFT: plan is now required

// Docs show:
const user = await client.users.create({
  email: "user@example.com"
});
// SDK error: Property 'plan' is missing in type
// → DRIFT: plan is now required by the SDK type

Setting up drift detection in CI

The minimal setup requires two things: your docs archive and your OpenAPI spec URL. The workflow runs on every release tag (or every PR if you want tighter feedback loops):

# .github/workflows/drift-detect.yml
name: API Drift Detection

on:
  push:
    tags: ['v*']         # on every release
  pull_request:          # or on every PR

jobs:
  drift:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Detect API drift
        run: |
          tar czf docs.tar.gz docs/ *.md
          RESULT=$(curl -sf -X POST https://snippetci.com/api/runs/queue \
            -H "Authorization: Bearer ${{ secrets.DOCSCI_TOKEN }}" \
            -F "docs_archive=@docs.tar.gz" \
            -F "openapi_url=https://api.example.com/openapi.json")
          
          DRIFT=$(echo "$RESULT" | jq -r '.finding_breakdown.by_kind.drift_detected // 0')
          echo "Drift findings: $DRIFT"
          echo "$RESULT" | jq -e '.status == "passed"'

Interpreting drift findings

DocsCI returns drift findings with three severity levels:

The compound effect: drift + broken examples

The most damaging scenario combines drift with broken code examples: your API changes, which causes the curl example in your docs to return an error, which causes the SDK example to fail, which causes the test in your CI to break, which you fix by updating only the test — not the docs. DocsCI breaks this cycle by making the docs the first thing to fail when an API contract changes.