Breaking changes

All API resources needs to be updated from time to time. Most of the changes made to our APIs are not breaking changes, which means that API clients can continue to request our APIs as before. Good examples of this is adding fields to response, input or filter. Sometimes we need to release breaking changes to our APIs, like removal of some fields or change datatypes or names of filters. In these cases we allow API clients to keep requesting the old and deprecated version of the API resource for a short time period.

When setting up a new API clients it is important to specify the e-mail to the person responsible of the API client. When we have released API resources with breaking changes, the responsible person will get notified about the changes by e-mail. Note that since all API clients using the RamBase APIs are required to specify which API resources they are using, only the affected API clients will get notified. In addition to receiving e-mails about the deprecated APIs, it is also possible to see which deprecated APIs an API client is using by navigating to the application called APICLIENTS in the RamBase client.

Migrating to the new version

When finding out that your API client is using deprecated versions of API resources, we recommend that you navigate to the changed API resources in our documentation pages. Here you can read desciptions of what's changed and compare the old version with the new version. At this point you are left with the following options:

1. Wait until the expiration time is reached and the API client will automatically switch to the new version. This is typically six months after the release. Note that after the expire time is reached you will not be able to go back to the old and deprecated version.
2. Start using the new version right away. Navigate to the application called APICLIENTS in the RamBase client and find the specific API resource and press the button Expire now. Note that it's also possible to configure your API client to never use deprecated versions and automatically start using new versions right away.
3. Try out the new version (recommended). Read more about this in the section below.

Try out the new version

In many cases it's preferrable to try requesting the new API resource version with the breaking changes before expiring the deprecated version. Each API resource has its own version history, which typically starts with version 1 and increments by one for each change. Some of these changes might be breaking changes, but usually they are not. The old and deprecated version will always be lower than the new version.

By adding the query parameter $useMinimumVersion you can force your request to use the newest API resource version:

In the example above, the newest version of the API resource is version 38. Maybe the deprecated version you API client would be using was version 37. So now you can try out the new version 38 by adding this query parameter, while still using the deprecated version 37 in your production code.

Note that the query parameter is named use minimum, which means that when newer versions of this API resource is released, the request will use the newest version (unless it is a new breaking change). This means that this query parameter can safely be put to production code!

An example

Imagine our API resource for retrieving sales orders is currently in version 3. The version history could look like this:

In this case version 1 and 2 is disconinued, meaning that it is not possible to request them.

As part of our continuous effort to improve our API resources, we might decide to remove a field, e.g. UglyField. The version history now looks like this:

In the process of releasing version 4, all API clients using version 3 of the API resource was set to continue using version 3 in six more months. All the API clients using this API resource receives a notification by e-mail about the breaking change. It is possible to browse and investigate the breaking changes in the documentation pages.

Some of the API clients might choose to expire the deprecated API right away through the application called APICLIENTS in the RamBase client. They will then start using version 4 of the API resource.

Some of the API clients might choose to not do anything and wait until the expiration date is reached.

Some of the API client might choose to try out the new version by adding $useMinimumVersion=4 to the API request in their testing environment. Now the production code is still requesting version 3, but version 4 is used in the test environment. After removing all references to UglyField they release the code to production. If anything goes wrong, the code can be rolled back by removing the $useMinimumVersion parameter. The requests will then use version 3 again.