Skip to main content

Versioning and deprecation

The CalendarPipe REST API is versioned in the URL. Every endpoint lives under /api/v1, and the same version appears as info.version in the OpenAPI description. Pin your client to that path and it keeps answering the way it does today.

What we can change without a new version​

These are additive, and your integration should tolerate them:

  • New endpoints, and new optional request fields on existing ones.
  • New fields in a response object. Parse leniently — ignore keys you do not recognise rather than rejecting the payload.
  • New values in an enum where the field's description says the list is open, such as a new provider.
  • New error codes. Handle an unfamiliar code by falling back on the HTTP status.

What counts as breaking​

Removing an endpoint or a field, renaming either, tightening validation on an existing field, or changing what a status code means. Anything in this list gets either a new version or the notice period below.

How a deprecation is signalled​

When an endpoint or a field is on its way out, all of the following happen before it is removed:

  1. The operation is marked deprecated: true in the OpenAPI description, so generated clients warn at build time.
  2. Its responses carry a Deprecation header giving the date the deprecation took effect, and a Sunset header giving the date it stops working. Both are HTTP dates.
  3. The page for it here says what to use instead.
  4. It is announced in What's new.

We give at least 12 months between the Deprecation date and the Sunset date. A removal without that notice would only ever happen to close a security hole, and we would say so.

The same commitment is published machine-readably as info.x-deprecation-policy in the OpenAPI description, so a client generator can read the notice period without parsing this page.

Nothing is deprecated today.

Last updated on