Hi everyone,
My name is Gerard, and I’m a software engineer at FreeAgent. I’m dropping a message here today to let you know about a change we’re planning to make to the API.
What’s changing?
We’re planning to start using versioning on our API endpoints.
Why are we making this change?
Currently, whenever we want to make a potentially breaking change to the API, we have to post on the forum about it and give you some notice of the change. This isn’t ideal as it means we can’t deploy some changes as fast as we’d like and it also means that you (our users) don’t get the benefit of the changes for a while. In addition, if you aren’t prepared or haven’t seen the announcement, then deploying the change could still potentially break your integration.
By using versioning, we hope to be able to deploy these breaking (or non-backwards compatible) changes faster and with less risk.
How will it work?
Version numbers will be date based. In order to access a particular version of an endpoint, you’ll have to pass a header in your request (X-Api-Version) with the date of the new version you’re trying to access (e.g. 2024-06-01). If there is a version of that endpoint matching that date, then you’ll get the new behaviour. If there isn’t then it’ll fall back to the previous version.
We won’t have too many versions of an endpoint active at the same time, especially if a new version fixes a bug in an older version, so we’ll come up with a deprecation policy soon as well and share that with you here.
If no version number is supplied, then you’ll get back the oldest version of the endpoint (i.e. the version of the endpoint as it was before we started using versioning). This should mean that integrations not supplying version numbers will still work as normal.
Will every change be a new version?
A new version of an endpoint will only be used when we consider the change to be non-backwards compatible (i.e. a breaking change). For example deleting an attribute, modifying the name of an attribute or changing the meaning of the response.
Changes which we would consider to be backwards compatible would not generate a new version. For example adding a new endpoint, adding an attribute to an existing endpoint or fixing a bug with the existing response.
When will it happen?
We’ve only made a few non-backwards compatible changes in the last couple of years, so rolling out a new version of an endpoint should still be few and far between. Adding in this infrastructure though means we’ll be ready if a new version is needed.
We’re sharing the plan now to give you a heads up in advance, and to ask for any feedback.
Can I see an example?
The technical details of how the versioning will work can be found on the API documentation here: https://dev.freeagent.com/docs/versioning. We’ll also be updating individual endpoint documentation where there are multiple versions available.