Upgrading to a new API version
The API Evolution concept
The original finAPI Access API has evolved continuously, but also kept backward-compatible for more than 9 years to make API change adoption as easy as possible for API consumers. The downside of keeping the API backward-compatible for such a long time is that new features had to be added in a way that does not break previous implementations. This created a lot of different API variants and ways that services could be called and several deprecated services and properties, making API implementation for new customers more and more complicated.
Starting with API V2, we introduce the concept of “API Evolution”: We still keep backward compatibility for an existing API Version but in parallel offer new API versions. This allows us to do breaking changes and to implement new features that would not be possible to add cleanly in a backward-compatible way.
API evolution also means that a new API is not completely recreated from scratch, but evolved from the previous one in a way that makes customer adoption as easy as possible.
With the introduction of a new API, the previous API is marked as “deprecated”, meaning it will still get maintained, but new features and services will only be added to the latest API version.
Switching between API versions
As a customer, you are bound to a specific version of the API, and only that version is accessible. Attempts to call services from a different API version will result in an HTTP 403 error with an “API Version mismatch” message.
The switchApiVersion service allows you to switch your client to a new API version which will be active from that point on. In case you have switched to API V2, the service allows you to switch back to API V1 within 7 days.
Our sandbox environment allows you to evaluate a new API version first and adjust your client accordingly before you switch to the new API for production.
When performing the API switch, it’s important to keep in mind that at any point in time, only API V1 or V2 can be active. Because of this reason, we recommend performing a hard switch.
Ideally, to avoid issues, you can perform the switch to the new API version V2 and roll out your new release during the finAPI scheduled downtime window. This would be the best solution, since finAPI APIs will not be available anyway during this period, and the impact will be minimal.
If this is not possible, a second option would be to perform the API migration at a time of your choosing, when it would suit you best to have the downtime needed for the migration. Choosing the time for the switch has the advantage that you can be flexible and select a time slot with the least usage of your application.
There is a third option to switch, in case you are using rolling deployment without downtime for your application. When switching to the new API V2, only the instances already using API V2 will work. All the others will trigger an error message (error code 403 - “API Version mismatch”). In this case, we recommend that you implement an error-handling for these API version mismatch errors, and display a message to your users telling them that your application is currently in the process of an update, and the user should retry in a few minutes (or however long you expect the redeployment of all instances to take). During this time, the instances should be switched to API V2 one by one. In the end, when API V1 is completely replaced by API V2, the error will no longer take place and all will work as expected.
API migration How-To
For each newly introduced API Version, we provide a detailed migration guide describing all necessary steps to adjust your API client from the previous to the new version.
Please note: The migration documentation covers the new API at the time when it is introduced. Later extensions made to the new API over time will not be covered there.
Available migration guides:
For a complete overview of the extra features in API V2, please see: