API Versions

Overview

API version defines the behavior of your API, including mandatory parameters in requests, the body of reponses, the objects returned by webhooks. The API constantly evolves by adding new functionality, improving responses, etc. We recommend you to upgrade your API version regularly to take advantage of those changes.

If a change in API breaks backward compatibility, the new API version is released (see the details here).

Each API version is named by the date when it was issued, e.g., "2023-10-31".

Below are the main rules of using and managing API versions.

API version in request and response

The API version is not specified in the URL of an API request. Instead, you can optionally pass the API version in the request header in the Version parameter. For example:

curl -X GET "https://dev.bpcbt.com/api2/sessions/test_aksdhauedqiuwehdiqwbdq" \
-H "Authorization: Bearer 6HUXQFbeomV1zf5i8cgm5W8KfncENVEa5uh8RngB" \
-H "X-Version: 2023-10-31" \

By default, the current version is used. To use another API version, specify it in API requests.

API response header always contains the version in X-Version parameter (format: 2023-11-15).

If the API version was not passed in the request, then the response contains the default API version.

API version compatibility

A new API version is released after adding changes that break backward compatibility. Such changes become available only in a new version.

Backward-compatible changes are available in every version and don’t require a version re-release. The examples of backward-compatible changes:

• Adding new API resources;
• Adding new optional request parameters to existing API methods;
• Adding new parameters to existing API responses;
• Changing the order of parameters in existing API responses;
• Changing length or format of the strings with unknown internal structure, such as object identifiers, error messages, etc. Such strings are processed as a whole - they can be saved or passed, without trying to interpret their content. The examples of changes related to such strings:
  • Changing text of error messages in responses;
  • Changing length of object identifiers (the only limitation is 255 symbols);
• Changing case in header names of responses;
• Adding new webhooks;
• Adding optional headers to requests;
• Adding headers to responses.