Third-Party OpenAPI Change Monitor

Monitor public OpenAPI 3.x and Swagger 2.0 specifications for structural changes between runs. Each specification URL produces one dataset record with a persistent hash, API-size summary, and review-oriented change list.

This Actor is designed for integration, platform, and reliability teams that depend on APIs they do not control. It can surface removed paths or operations, new required request inputs, changed response/schema definitions, security-requirement changes, and additive API updates before a human reviews the source specification.

It does not guarantee that a change will or will not break an integration. potentially_breaking is a conservative heuristic, not a compatibility proof.

Independent community Actor: This Actor is not affiliated with or endorsed by the OpenAPI Initiative, SmartBear/Swagger, or any API provider whose public specification you monitor. You are responsible for choosing lawful public URLs and a polling schedule that respects each provider's terms and infrastructure.

Input

Field	Required	Description
monitorId	Yes	Stable ID for one independent watchlist, for example production-vendor-apis.
specUrls	Yes	1–50 public HTTP(S) OpenAPI or Swagger URLs. JSON and YAML are supported. Duplicate URLs are checked once.
ignoreJsonPointers	No	Exact RFC 6901 paths removed before hashing and comparison, useful for volatile metadata such as /info/x-generated-at.
timeoutSeconds	No	Per-URL request timeout, 5–120 seconds (default 30).
maxChanges	No	Maximum detailed entries in each output changes array (default 200, maximum 500). Summary counts still cover every detected change.
maxConcurrency	No	Concurrent URL checks, 1–10 (default 5).

The default input checks the public Swagger Petstore specification, so a default run completes without credentials. Replace the default monitorId and URL before creating a production schedule.

Example:

{
  "monitorId": "production-vendor-apis",
  "specUrls": [
    "https://petstore3.swagger.io/api/v3/openapi.json"
  ],
  "ignoreJsonPointers": [
    "/info/x-generated-at"
  ],
  "maxChanges": 200
}

Output

Every URL emits one dataset record.

status	Meaning
initial_snapshot	The first valid parsed specification was stored.
unchanged	The normalized parsed document matches the previous successful check.
changed	The parsed document changed; counts and detailed structural change records are included.
fetch_error	The URL was invalid, blocked, unavailable, too large, or returned an HTTP/network error. Prior state is preserved.
parse_error	The response was not a valid OpenAPI/Swagger JSON or YAML object. Prior state is preserved.

Common fields include:

• url, final_url, checked_at, http_status, and content_type
• spec_format, openapi_version, api_title, and api_version
• path_count, operation_count, and component_schema_count
• content_hash, previous_hash, and state_store_mode
• change_count, severity counts, change_summary, changes, and changes_truncated

A detailed change record contains severity, type, location, message, and compact before/after values where useful.

Severity labels

• potentially_breaking — conservative signals such as removed operations, new required parameters, or removed schema properties.
• review — changes whose compatibility depends on client behavior, such as response schemas, operation IDs, server lists, or security requirements.
• additive — new paths, operations, optional parameters, responses, or optional properties.
• informational — version, deprecation, or unclassified document metadata changes.

Persistence and scheduling

Successful parsed snapshots are stored in the named key-value store third-party-openapi-change-monitor-state-v1. A named store is used because the default run store is run-scoped in Apify Cloud. Snapshot keys are derived from monitorId + URL, so one stable monitorId retains history while different watchlists remain separate.

Schedule the Actor hourly, daily, or weekly and route changed records through Apify integrations or webhooks. The Actor itself does not send external messages.

Charging behavior

The code emits one openapi_spec_check charge event only after a specification is successfully fetched, parsed, compared, and stored. Invalid URLs, fetch failures, and parse failures are not charged. Refer to the live Actor listing for the current event price after publication.

Security and data handling

• Only public HTTP(S) URLs are supported.
• Private, loopback, link-local, multicast, and reserved destinations are blocked, including redirect targets.
• Credentials embedded in URLs are rejected, and the Actor has no input field for authorization headers or secrets.
• Parsed public specifications are stored in the named key-value store to enable later comparisons.
• Responses larger than 5 MB are rejected.
• Cyclic YAML aliases, nesting beyond 100 levels, and documents exceeding 200,000 parsed nodes are rejected to keep parsing bounded.

Local development

python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
.venv/bin/python smoke_test.py

The smoke test runs the Actor three times against a deterministic local fixture and verifies initial_snapshot → unchanged → changed, including removed-operation and new-required-parameter signals. Private URL access is enabled only inside that local test process.

Limitations

• External $ref documents are not fetched or dereferenced. Changes to the $ref value are seen, while changes inside a separately hosted referenced document require adding that document as another specUrls entry if it is itself a complete OpenAPI document.
• The Actor compares published specifications; it does not probe live endpoints or prove that implementation and documentation match.
• Classification is intentionally conservative and cannot replace contract tests, generated-client tests, source changelogs, or engineering review.
• Very large change sets are summarized and truncated according to maxChanges.
• Authenticated or private specifications are intentionally unsupported in this public Actor design.