Skip to content
OclavexOclavex Docs

API versioning

The entire API is versioned in the path: everything lives under api/v1. There is exactly one current version.

Additive changes are safe — build for them

Section titled “Additive changes are safe — build for them”

Within v1, the contract evolves additively. Expect, without notice:

  • New optional request fields (e.g. the fingerprint components map was added this way — omitting it keeps the old behavior).
  • New response fields. Deserialize leniently; never fail on properties you don’t recognize.
  • New webhook event types and new fields inside event data — the payload is non-strict by contract.
  • New error codes — treat unknown codes as a generic failure of their HTTP status.
  • New endpoints, new enum values, new scopes.

A client that ignores what it doesn’t understand never breaks on an additive change.

What would be breaking

Section titled “What would be breaking”

Removing or renaming a field, changing a field’s type or semantics, tightening validation on existing input, or removing an endpoint.

None of these happen inside v1. That is a commitment rather than an intention: the set of routes v1 serves is recorded, and Oclavex’s build fails if one of them disappears. An endpoint you integrate against today cannot be removed from under you by an ordinary release.

If a breaking change is ever necessary, it ships as a new version path — api/v2 — with v1 still running alongside it. There is no v2 today and none planned.

Deprecations

Section titled “Deprecations”

If an endpoint is ever slated for replacement, you find out from the endpoint itself rather than from release notes you might never read. A deprecated endpoint returns three headers:

Deprecation: true
Sunset: Sun, 31 Jan 2027 00:00:00 GMT
Link: <https://docs.oclavex.com/...>; rel="deprecation"
  • Deprecation (IETF draft) marks the endpoint as superseded. It keeps working.
  • Sunset (RFC 8594) is the date it stops responding, as an HTTP-date. This is the one to schedule against.
  • Link with rel="deprecation" points at what to migrate to.

A practical way to use them: log a warning whenever a response carries Deprecation, and alert when Sunset is less than one release cycle away. That turns a migration deadline into something your monitoring raises with you, rather than something you discover as an outage.

No endpoint is deprecated today, so you will not see these headers yet.