API Evolution

The following changes are expected and considered compatible:

Addition of new features to the API.
Addition of new optional parameters to requests.
Addition of new fields in API responses.
Change in the order of fields.
Addition of new elements in enumerations.

Versioning

The API version consists of 4 elements: major, minor, patch, and release candidate.

The version in the URL path represents the major element of the API version.

The evolution of the version occurs as follows:

Major: incompatible changes, with a contract break (v1.0.0 → v2.0.0)
Minor: compatible changes, without a contract break (v1.1.0 → v1.2.0)
Patch: clarifications to specifications, without functional changes (v1.1.1 → v1.1.2)

When a major evolution occurs, the previous version will remain available for a minimum of X days, and all clients are going to be noticed.

Changes without a contract break and clarifications to specifications can occur at any time. Clients should be prepared to handle these changes without breaking. (We always notice all clients)

Changelog example

[1.0.0] - 2024-01-07

Added

Example

Changed

Example

Removed

Example