Skip to Content
DocumentationVersioning & Deprecation

Versioning and Deprecation

So your integration never breaks without warning, we commit in writing to what can change in the contract and what cannot.

The major version lives in the URL

/api/public/v1

The major version only increases when a backwards-incompatible change is unavoidable. v1 and v2 run side by side for a period; you are never asked to migrate overnight.

Changes considered backwards compatible

These do not require a new major version, and your client must tolerate them:

  • Adding a new field to a response.
  • Adding a new endpoint or a new optional query parameter.
  • Adding a new value to an enum (for example a new alarm type).
  • Changing the wording of an error message — error.code stays stable, read that.
  • Changing the order of fields in the JSON.
Write your client accordingly

Ignore unknown fields, do not crash on unknown enum values, and branch on error.code rather than the message text. Those three rules protect your integration through most upgrades.

Changes that require a new major version

  • Removing or renaming a field.
  • Changing the type of a field.
  • Making an optional field required.
  • Changing default behaviour.
  • Removing an endpoint.

The deprecation process

When an endpoint or field is going away the process is not silent — the API itself warns you. There are at least 180 days between the announcement and the shutdown.

Announcement

It is written in the changelog, and machine-readable headers are added to every response from the affected endpoints.

Migration window

Old and new behaviour run together for at least 180 days. That is your window to migrate.

Shutdown

After the Sunset date the endpoint returns 410 Gone.

Warning headers

Every request to a deprecated endpoint returns these headers:

HeaderMeaning
DeprecationThe date the endpoint was deprecated (RFC 9745).
SunsetThe date the endpoint will be shut down (RFC 8594).
LinkAddress of the migration guide, with rel="sunset".
WarningA short, human-readable explanation.

Example:

HTTP/1.1 200 OK
Deprecation: Sat, 01 Aug 2026 00:00:00 GMT
Sunset: Mon, 01 Feb 2027 00:00:00 GMT
Link: <https://developer.frigolive.nl/en/docs/versioning>; rel="sunset"
Warning: 299 - "This endpoint was replaced by /shipments/{shipment_id}/tracking/."

The warning headers are returned even when the request fails, so the breakage shows up in your logs before the shutdown.

The easiest way to watch for this

Log responses carrying a Sunset header in your backend and raise an alert:

response = requests.get(url, headers=headers, timeout=20)
sunset = response.headers.get("Sunset")
if sunset:
    logger.warning("Frigolive endpoint will be retired: %s -> %s", url, sunset)

You can also follow the changelog through its Atom feed.

Changelog

Every contract change is published in date order on the Changelog page.

SDKs & OpenAPI