API Versioning and Deprecation

WorldMonitor versions public REST APIs in the URL:

https://api.worldmonitor.app/api/<domain>/v<major>/<operation>

For example, /api/market/v1/list-market-quotes is a version 1 operation. Different domains may advance independently, so clients should use the version present in each path rather than assuming one global API version.

Compatibility within a major version

Within a published major version, WorldMonitor may add optional request fields, response fields, operations, and enum values. Existing fields keep their meaning and type. We do not remove or rename operations or fields, make an optional field required, or otherwise introduce an intentionally breaking change without publishing a new major-version path.

Clients should ignore response fields and enum values they do not recognize. The bundled OpenAPI specification is the source of truth for the currently published contract.

Protobuf compatibility check

The public API is JSON over HTTP. On pull requests that touch proto paths, CI runs make breaking against origin/main with Buf's FILE, PACKAGE, and WIRE_JSON rules. That job fails the proto-breaking check-run when the baseline is missing or a rule is violated; it is not yet one of the deploy-gate required contexts that branch protection aggregates for merge. WIRE_JSON is intentional: generated JSON field names and shapes are part of the versioned REST contract. The repository does not currently ship binary-protobuf consumers, so the binary WIRE rule is intentionally not enabled. The CI workflow fetches full Git history so a missing origin/main baseline fails the check instead of allowing a vacuous pass.

Deprecation timeline

When WorldMonitor replaces or retires a public REST version or operation:

1. We publish the replacement and migration guidance in the API documentation and changelog.
2. The deprecated surface remains available for at least six months after the public deprecation announcement.
3. We publish a specific shutdown date at least 90 days before that date.
4. Until shutdown, requests to the deprecated surface carry the HTTP signals below.

Security, privacy, legal, or upstream-provider emergencies may require a faster change. When that happens, we publish notice and migration guidance as soon as practical.

Machine-readable signals

Responses from a deprecated operation or version include:

Deprecation: @1782864000
Sunset: Thu, 31 Dec 2026 23:59:59 GMT
Link: <https://www.worldmonitor.app/docs/api-versioning>; rel="deprecation"; type="text/html"

• Deprecation is the date the surface became deprecated, expressed as an HTTP Structured Field date.
• Sunset is the final availability date in HTTP-date format.
• Link with rel="deprecation" points to migration guidance or this policy.

The OpenAPI operation is also marked deprecated: true. Agents should treat Deprecation as a migration warning and stop scheduling calls beyond the Sunset date.

No currently supported endpoint sends these headers merely because its path contains v1. A version number identifies a compatibility boundary; it does not by itself mean the version is deprecated.

Client guidance

• Pin the complete versioned path from the OpenAPI document.
• Regenerate or update clients when a replacement major version is published.
• Monitor Deprecation, Sunset, and Link on successful and error responses.
• Subscribe to the changelog for human-readable release notices.