Versioning

The API employs a versioning scheme to handle backward-incompatible changes. The designation of each API version reflects the date of its publication. For instance, the version labeled 2024-03-21 was officially launched on Thursday, March 21, 2024.

Breaking changes, which are modifications with the potential to disrupt existing integrations, will be introduced in a new version of the API. These breaking changes include:

  • removing an entire operation
  • removing or renaming a parameter
  • removing or renaming a response field
  • adding a new required parameter
  • making a previously optional parameter required
  • changing the type of a parameter or a response field
  • removing enum values
  • adding a new validation rule to an existing parameter
  • changing authentication or authorization requirements

All supported API versions subject to additive (non-breaking) changes. These are modifications designed not to disrupt existing integrations and include:

  • adding an operation
  • adding an optional parameter
  • adding an optional request header
  • adding a response field
  • adding a response header
  • adding enum values

Specifying an API version

To specify an API version, you should use the Sartorius-Studio-Api-Version header. For instance:

curl --request GET \
--url "https://umetrics.studio/projects" \
--header "Sartorius-Studio-Api-Version=2024-03-21"

Requests without the Sartorius-Studio-Api-Version header will automatically default to the latest API version. Each response carries a header that indicates the specific version of the API that was actually used to handle the request.

Requests with an incorrect or no longer supported API version return a 400 error.

Upgrading to a new API version

Before upgrading to a new REST API version, it's essential to review the changelog for breaking changes. This will help you understand the modifications involved and guide you through the upgrade process for that specific version.

Supported API versions

The list of currently supported versions can be found in the left panel labeled as REST API REFERENCE.