SpecBreak Monitor

SpecBreak Monitor is a private-ready Apify Actor that watches OpenAPI 3.x documents, stores a baseline, and reports breaking API contract changes before downstream clients discover them in production.

It is designed as a self-service paid automation: a customer supplies one or more public OpenAPI URLs, schedules the Actor, and receives structured results in an Apify dataset or an optional HTTPS webhook. Apify handles execution, schedules, usage billing, and delivery. The Actor makes no AI-model calls, so variable costs stay low and results are deterministic.

What it detects

• Removed paths and HTTP operations
• Removed response status codes or media types
• New required query, header, cookie, or path parameters
• Removed parameters and parameter type changes
• Newly required request bodies or request properties
• Removed response properties
• Schema type and format changes
• Narrowed enum values
• Security requirements added or changed
• New deprecation markers

Every change includes a severity, stable change code, JSON Pointer, before/after evidence, and a breaking/non-breaking flag. Each run also records SHA-256 hashes for the baseline and current documents.

Automatic money and delivery flow

1. A customer finds the Actor in Apify Store and supplies public OpenAPI spec URLs.
2. The customer runs it once to establish a baseline, then uses an Apify schedule for recurring checks.
3. Each successful spec check triggers the spec-check pay-per-event charge.
4. The Actor stores the current baseline, writes a structured dataset result, and optionally sends a webhook only when changes exist.
5. Apify bills the customer and settles eligible developer payouts after account and identity setup.

The pricing hypothesis in the prepared listing is $0.05 per successful spec check, including platform usage. It is a starting test, not a revenue guarantee.

Quick local demo

PYTHONPATH=src python -m specbreak.cli \
  examples/petstore-v1.json \
  examples/petstore-v2.json \
  --json-out build/sample-report.json \
  --markdown-out build/sample-report.md

Test

$PYTHONPATH=src python -m unittest discover -s tests -v

Actor input

{
  "specs": [
    {
      "name": "Billing API",
      "url": "https://api.example.com/openapi.json"
    }
  ],
  "updateBaseline": true,
  "failOnBreaking": false,
  "webhookUrl": "https://hooks.example.com/openapi-change"
}

Inline JSON specs are supported with a spec object instead of url. URLs containing credentials are rejected, query strings are redacted from outputs, redirects are revalidated, and localhost/private/link-local/reserved IP targets are blocked.

Output states

• baseline_created: first successful observation; no alert
• no_change: current SHA-256 matches the stored baseline
• changes_detected: one or more structured changes were found
• error: that spec failed validation or retrieval; other specs continue

Limits and scope

• OpenAPI 3.x JSON and YAML are supported.
• Remote $ref documents are not fetched; local #/... references are resolved.
• This detects contract risk from the document diff. It does not prove that an implementation conforms to either document.
• Public HTTP can be enabled explicitly, but HTTPS is the default and recommended mode.
• URL controls reduce SSRF risk but should still be paired with Apify limited permissions and normal platform isolation.

Private deployment

The package is complete and tested locally. The remaining owner-only steps are listed in docs/PUBLISH_CHECKLIST.md. No repository, Actor, or listing has been made public.

License

Copyright © 2026. All rights reserved. Commercial use is intended through the owner's published Apify Actor.