API versioning

Learn about Monite API versioning, breaking and non-breaking changes, and how to upgrade your integration when necessary.

When you connect to the Monite API platform, you always communicate with a certain version of the API. Having different API versions allows us to implement breaking changes in an API in a backward-compatible way, which gives you full control over when and how you want to switch your Monite integration to a new API version.

API versioning scheme

To refer to a specific version of a Monite API, you need to know the version identifier. We provide these identifiers using the date-based pattern: YYYY-MM-DD, for example 2024-05-25 or 2024-01-31.

Version in a header or in a URL?

All Monite API URLs also contain a /v1 suffix in the URL path. Currently, we do not plan to change this suffix and therefore we simply reserve it for future use, for example, in case we need to significantly revamp the entirety of our API structures.

Versioning API requests

You must choose a specific API version by adding an X-Monite-Version HTTP header to every API request you send to the Monite API platform:

1curl -X GET 'https://api.sandbox.monite.com/v1/entities' \
2     -H 'X-Monite-Version: 2024-05-25' \
3     -H 'Authorization: Bearer eyJ0eXAiOiJKV1Qi...5HHaosPfssfu0o'

The same header is added to every response you receive from the Monite API:

X-Monite-Version: 2024-05-25

If you do not provide an explicit version via the X-Monite-Version HTTP request header, Monite API will return an HTTP 400 error:

1{
2    "error": {
3        "type": "missing_api_version",
4        "message": "Missing the x-monite-version HTTP header"
5    }
6}

Default API version

In addition to the API version specified with each API call, there are a number of cases when Monite needs to perform various operations (such as asynchronous OCR that require a defined API version. To specify this version, call PATCH /settings and set the desired value to the api_version setting as follows:

1curl -X PATCH 'https://api.sandbox.monite.com/v1/settings' \
2     -H 'X-Monite-Version: 2024-05-25' \
3     -H 'Authorization: Bearer YOUR_PARTNER_TOKEN' \
4     -H 'Content-Type: application/json' \
5     -d '{
6       "api_version": "2023-09-01"
7     }'

Breaking changes

Breaking changes are such changes in the API that require all API clients to modify their code to incorporate these changes. Examples include renaming and deletion of API elements, narrowing down certain requirements, as well as changes of the business logic that exceed the common expectations from a regular bug fix.

Here is the list of breaking changes that we use as a guideline for introducing a new version in our API:

  • Renaming or deleting an API endpoint.
  • Renaming or deleting a field in a request or response.
  • Renaming or deleting an HTTP header. (Note that HTTP headers are case-insensitive, so changing the letter case is not considered a breaking change.)
  • Renaming or deleting a query parameter.
  • Changing the data type of an API field, HTTP header, or query parameter.
  • Changing the HTTP status code of a response.
  • Making non-required fields, query parameters, or HTTP headers required in an API request.
  • Narrowing down the range of allowed values for a field, query parameter, or an HTTP header in an API request.
  • Significant change of a business logic that leads to the corresponding changes on the API client’s side.

Non-breaking changes

In JSON-based REST APIs, every additive change is typically considered to be non-breaking. API clients must program their implementations in a way that can handle new fields in API responses without causing any errors and exceptions.

Below is a list of API changes that we consider to be non-breaking, so they can appear in the current API version:

  • Adding a new API endpoint.
  • Adding a new optional field, query parameter, or HTTP header to an API request.
  • Adding a new field or HTTP header to a response.
  • Making required fields, query parameters, or HTTP headers non-required in an API request.
  • Expanding the range of allowed values for a field, query parameter, or an HTTP header in an API request.
  • Insignificant change of a business logic that does not require any changes on the API client’s side.
  • Changing the text of an error message in a response.

How to upgrade

We recommend that you always migrate to the latest version of the Monite API, since this allows you to benefit from all the latest developments and functionality incorporated into these versions. However, we understand that sometimes migrating to a new API version might be complicated and requires additional efforts and preparations from your side.

Follow these steps to migrate your code to a new version of Monite API:

  1. Explore all the changes listed in Breaking changes.
  2. Migrate your code to the new API version. Test the changes in Monite Sandbox environment.
  3. After you ensure that there are no new errors related to the new API version, deploy these integration changes to production, connecting to Monite’s production environment.

Changelog

To review the latest changes between our API versions, visit the Release notes page.