Versioning and deprecation

The API’s major version is in its path: https://api.campone.ch/api/v1/public/. Every answer from it also names the exact version in a header:

X-API-Version: 1.0.0

What changes within v1

Within a major version, changes add to the API and do not take anything away: new endpoints, new optional fields in a request, new fields in an answer, new events. A field you use today keeps its name, its type and its meaning. Write your integration so that additions do not break it:

• Ignore fields you do not know, in answers and in webhook bodies.
• Expect new values where the API lists values, such as a booking’s status. Handle a value you do not know without failing, for example by logging it and leaving the booking alone.
• Ignore events you do not know. An endpoint whose event_types list is empty gets the nine default events only; the four events added since then are opt-in, so an endpoint that subscribed to “every event” did not start receiving them unasked.

Breaking changes

A change that would break a working integration (a field renamed, removed or of another type, a different meaning, an endpoint gone) does not happen within v1. It ships as a new major version under its own path, /api/v2/, next to v1, and v1 keeps answering while you move.

How a version’s end is announced

When a version is going away, every answer from it carries three more headers:

Deprecation: true
Sunset: Sat, 31 Jul 2027 00:00:00 GMT
Link: <https://developers.grondia.com/guides/versioning/>; rel="deprecation"

• Deprecation: true says the version you are calling is deprecated.
• Sunset is the date after which it may stop answering, as RFC 8594 defines it. The date above is an example.
• Link points to this page.

The Changelog lists every change, with the API version it belongs to.

Grondia gives at least 12 months’ notice before a version’s sunset date. Today no version is deprecated, and no answer carries these headers.

Watch for them: log a warning, or raise an alert, the first time an answer carries Deprecation. The header reaches your integration even if nobody on your side reads an announcement.

In the sandbox

Every answer from the sandbox carries X-API-Version too, so you can check that your client reads it.