Skip to main content
WorldMonitor versions public REST APIs in the URL:
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. One domain currently deviates from that shape: shipping v2 puts the version before the domain — /api/v2/shipping/<operation> (e.g. /api/v2/shipping/route-intelligence). Every other domain is at v1 with the standard /api/<domain>/v1/ prefix.

​
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 will carry the HTTP signals below. (This is forward-looking policy: nothing is deprecated today, so no endpoint currently emits them.)
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

​
Policy discovery on current (non-deprecated) responses

RFC 9745 allows a Link with rel="deprecation" without a Deprecation header, so agents can find this policy before any surface is retired. Current WorldMonitor API and homepage responses may include:
That header is not a deprecation notice. It points at the static markdown policy (this HTML page is the human twin).

​
Signals on a deprecated operation or version

Responses from a deprecated operation or version also include:
  • 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 this policy or to migration guidance. On current surfaces it is policy discovery only.
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.