OpenAPI Contract Drift Monitor

Monitor public OpenAPI or Swagger JSON specifications on a schedule. The first successful check establishes a baseline; later checks report operations, parameters, request and response schemas that changed. Results are structured for alerting, triage, and automated API-client maintenance.

Why this complements endpoint health checks

An endpoint health check tells you whether a live URL responded and whether its observed JSON changed. This Actor watches the published contract itself: a removed operation, newly required request field, changed schema type, or removed response can be detected even before a client happens to call that path.

Input

{
  "specs": [
    { "name": "Petstore", "url": "https://petstore3.swagger.io/api/v3/openapi.json" }
  ],
  "monitorKey": "production-apis",
  "emitOnlyChanges": false
}

Use the same monitorKey and URL on recurring runs to compare against the Actor's private key-value-store baseline. The first successful run only creates a baseline. JSON OpenAPI 3.x and Swagger 2.0 documents are supported; YAML specifications are not currently supported. The URL is part of the baseline key, so changing the URL creates a new baseline.

What is compared

• HTTP operation additions and removals.
• Operation IDs and deprecation status.
• Parameter names, locations, required flags, and schemas.
• Request-body required flags and JSON/media schemas.
• Response codes, headers, and schemas.
• Schema types, properties, required properties, enums, references, and common constraints.

Changes are classified as BREAKING, POTENTIALLY_BREAKING, or NON_BREAKING. Local JSON Pointer $ref values are expanded with a depth limit; remote $ref targets are not fetched. The classification is a review aid, not a formal compatibility proof: complex schema composition and version-specific semantics can be ambiguous, and consumers may depend on undocumented behavior. Always review the changed contract before releasing or rolling back a client.

Cost and output controls

Each emitted dataset row represents one specification check. emitOnlyChanges=true suppresses successful unchanged rows while still updating the baseline; errors and initial baselines are still emitted. A SUMMARY key-value record contains run totals. The Actor does not call an LLM, use proxies, or require API credentials.

Safety and limits

Only public HTTPS URLs are accepted. Credentials, private or reserved IP addresses, custom ports, and credential-like query parameters are rejected. Redirects are followed at most twice, with destination checks. Responses are capped at 2 MB and requests time out after at most 15 seconds. DNS checks are best-effort; do not treat this Actor as a network security boundary. It fetches specification documents only and does not call API operations or test their behavior.

The actor supports up to 20 URLs per run. Change output is capped at 100 entries per specification to bound dataset size. A successful fetch and valid document are required before a baseline is updated; fetch failures do not erase a prior baseline.