Schema Drift Detection

Pro and Enterprise only.

What is schema drift?

Schema drift happens when the real API you're mocking changes its OpenAPI spec — adding endpoints, removing them, or changing response shapes — while your mock configs stay the same.

If your mocks drift from the real API, your tests may pass against the mock but fail against the real service. Drift detection catches this early.

---

How it works

1. You upload a schema with a source URL (the upstream spec location)
2. On demand, Mockra fetches the current spec from that URL and compares it to your stored version
3. Differences are classified and stored as a drift alert
4. The dashboard shows you exactly what changed

---

Drift types

Type	What it means
NO_DRIFT	Spec matches — no changes detected
ENDPOINT_ADDED	A new path/method combination exists in the upstream spec that isn't in your schema
ENDPOINT_REMOVED	A path/method in your schema no longer exists in the upstream spec
RESPONSE_CHANGED	An existing endpoint's response schema or status codes changed
MULTIPLE	More than one type of change detected

---

Checking for drift

From the dashboard

Open any schema and click Check for drift in the Drift Monitoring panel. Mockra fetches the upstream spec and compares it immediately.

Via API

curl -X POST https://api.mockra.io/workspaces/{workspace_id}/schemas/{schema_id}/check-drift \
  -H "Authorization: Bearer {token}"

Response when drift is detected:

{
  "drift_status": "ENDPOINT_ADDED",
  "has_unacknowledged_drift": true,
  "last_drift_checked_at": "2025-03-15T10:30:00Z",
  "diff_summary": {
    "added": [
      { "method": "POST", "path": "/users/{id}/verify-email" }
    ],
    "removed": [],
    "changed": []
  }
}

---

Viewing drift details

When drift is detected, the dashboard shows:

• Which endpoints were added, removed, or changed
• When the drift was last checked
• Whether drift has been acknowledged

---

Acknowledging drift

Once you've reviewed the changes and updated your mock configs accordingly, mark the drift as acknowledged:

From the dashboard

Click Acknowledge in the Drift Monitoring panel.

Via API

curl -X POST https://api.mockra.io/workspaces/{workspace_id}/schemas/{schema_id}/drift/acknowledge \
  -H "Authorization: Bearer {token}"

Acknowledging drift clears the has_unacknowledged_drift flag on the schema. The drift history is preserved — acknowledging doesn't delete the diff.

---

Responding to drift

After acknowledging, take action based on the drift type:

Endpoint added — A new endpoint exists upstream. Upload the updated spec to create a mock config for the new endpoint.

Endpoint removed — The upstream API dropped an endpoint. Decide whether to remove the mock config or keep it for tests that still need it.

Response changed — The response schema or status codes changed. Update the mock config body or status code to match the new upstream behavior.

---

Drift detection requirements

For drift detection to work, the schema must have a source URL — Mockra needs to know where to re-fetch the spec.

Schemas uploaded via URL have a source URL set automatically.

Schemas uploaded via file or raw paste do not have a source URL by default, but you can add one after upload:

curl -X PUT https://api.mockra.io/workspaces/{workspace_id}/schemas/{schema_id}/source-url \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{ "source_url": "https://example.com/openapi.yaml" }'

The URL must be HTTPS. Once set, the schema behaves identically to a URL-uploaded schema for drift detection purposes. In the dashboard, the Drift Monitoring panel shows a URL input form for any schema that doesn't yet have a source URL.

---

Getting drift status

curl https://api.mockra.io/workspaces/{workspace_id}/schemas/{schema_id}/drift \
  -H "Authorization: Bearer {token}"

Response when no drift has been checked yet:

{
  "drift_status": null,
  "has_unacknowledged_drift": false,
  "last_drift_checked_at": null,
  "diff_summary": null
}