API contracts rarely fail all at once. More often, a required field disappears, an enum gains a value that an older client cannot handle, or an endpoint starts returning a different content type. A scheduled web cron check can catch that schema drift before it becomes a customer-facing outage.
This guide shows how to build a safe, low-noise monitor that compares a trusted API contract with the shape exposed in production. It complements ordinary scheduled API health checks: availability checks answer whether the endpoint responds, while contract checks answer whether clients can still understand the response.
What API schema drift means
Schema drift is any unplanned difference between the contract consumers expect and the contract a service currently exposes. The contract may be an OpenAPI document, JSON Schema, GraphQL schema, or a smaller internal definition of the fields and status codes that matter to a specific workflow.
Not every difference has the same risk. Adding an optional response field is usually compatible. Removing a required field, changing a number to a string, narrowing an allowed range, or replacing a documented 200 response with 202 can be breaking. The monitor should classify changes instead of treating every diff as an emergency.
Choose a stable source of truth
Start with a reviewed, version-controlled contract rather than a response captured from an arbitrary request. Store the approved baseline with the application release or in a dedicated contract repository. Record its service version and approval date so an operator can tell whether an alert reflects an unexpected deployment or a deliberately outdated baseline.
If the provider publishes an OpenAPI endpoint, download it through an authenticated, read-only request. Do not silently replace the approved baseline on every run; automatic replacement would make the monitor accept the very drift it is meant to detect.
Normalize before comparing
Raw specifications contain harmless volatility. Generated timestamps, server URLs, descriptions, example values, and property order can change without altering compatibility. Parse the document, sort object keys, remove approved volatile metadata, normalize equivalent nullable forms, and then calculate a canonical hash.
Keep normalization rules small and reviewed. A broad rule that deletes every unknown key can hide a meaningful constraint. Save the normalized representation or a concise structural diff so the alert explains exactly what changed.
Check both the declared contract and real behavior
A specification can remain unchanged while runtime responses drift. Use two layers:
- Contract check: retrieve the published schema and compare it with the approved baseline.
- Sample probe: call one or more safe read-only endpoints and validate status, content type, required fields, types, enum values, and key constraints.
Never use a monitoring request that creates, updates, or deletes production data. Use a dedicated test account and deterministic resource where possible. Protect the endpoint as described in secure web cron endpoint guidance, and keep credentials in the site's configured secret store rather than in the cron URL.
Classify compatibility with practical rules
A useful severity model keeps alerts actionable:
- Critical: an endpoint or required operation disappeared; authentication changed; a required property was removed; or a type became incompatible.
- High: a required field was added, an enum was narrowed, an allowed range shrank, or a success status changed.
- Medium: a new enum value may break exhaustive client code, a field became deprecated, or a response format changed on a secondary operation.
- Informational: optional fields or endpoints were added without changing existing behavior.
Adjust the rules to the languages and client libraries you support. An added enum value may be safe for a tolerant JavaScript client but unsafe for a generated client that rejects unknown values.
Design the scheduled job
Run the check often enough to shorten detection time without creating unnecessary load. For most public APIs, every 15 to 60 minutes is a reasonable starting point; high-risk internal integrations may need a shorter interval. If the provider exposes rate-limit headers, track them and follow the patterns in API rate-limit monitoring.
Use strict connection and total timeouts, retry only transient network failures, and add bounded exponential backoff. A timeout should produce an availability signal, not a false schema-change diff. Keep the last known-good baseline separate from the last attempted result.
Prevent duplicate and noisy alerts
Hash the normalized diff and include the hash in the incident key. Notify immediately for a new breaking change, suppress identical repeats for a defined window, and send a recovery event when the service matches the baseline again. The alert should include the affected operation, compatibility classification, first-seen time, baseline version, current schema hash, and a redacted diff.
Route schema alerts separately from transport failures. For infrastructure-wide context, pair the job with cron job monitoring and an independent HTTP security header check.
Use an approval workflow for intentional changes
When a change is planned, the service owner should update the contract through review, run consumer contract tests, deploy compatible clients where necessary, and then promote the new baseline. Make baseline promotion an explicit action with an audit record. Do not let an alert button overwrite history without review.
Test failure modes before relying on the monitor
- Remove a required field in a staging response and confirm a critical alert.
- Add an optional field and confirm it is informational or ignored by policy.
- Return HTML from the endpoint and confirm the content-type check fails clearly.
- Simulate 429 and 503 responses and verify bounded retries.
- Corrupt the baseline and confirm the job fails closed rather than approving it.
- Restore the original contract and confirm a single recovery notification.
Implementation checklist
- Use a reviewed, versioned contract as the baseline.
- Normalize only known non-semantic fields.
- Compare declared schemas and safe runtime samples.
- Classify additive, risky, and breaking changes.
- Use read-only credentials, timeouts, rate limits, and bounded retries.
- Deduplicate alerts by normalized diff hash.
- Require review before promoting a new baseline.
- Test breaking, compatible, transient, and recovery paths.
A focused contract monitor does not replace integration tests or careful API versioning. It adds an independent production signal: the service contract clients depend on is still present, compatible, and behaving as expected.