Skip to main content

Versions

The version is in the path: every route lives under /api/v1/.

What v1 promises​

Inside v1, things are only added:

  • New fields in a row or in an envelope.
  • New values of an enumeration: a new state, a new label in labels, a new source of an expected day.
  • New query parameters, always optional.
  • New routes.
  • New error codes, for situations that could not happen before.

Nothing is removed, renamed or given another meaning. A field that exists keeps its name, its type and what it counts.

Write your client so that additions never break it: ignore the fields you do not know, and treat an unknown value of an enumeration as "something else" rather than an error.

What a v2 is​

A change that would break a client, such as removing a field, renaming one or changing what a number means, goes to a new version under /api/v2/. When that happens, v1 keeps answering alongside it for a period announced in the changelog, so there is time to move.

What is not a change of the API​

The numbers of a report change when the company's data changes: an approved mark, a corrected schedule, a new holiday. That is the report doing its job, not the API changing. The rules that compute them are the app's, the same for the reports page, its Excel and this API.

The detail of an error is a message for a person and can change wording at any time; its code cannot.