The OpenAPI versioning and obsolescence policy aims to strike a balance between:
- The need of API consumers for a stable API to code against.
- Allowing us to iterate quickly so we can provide a better product, faster.
Versioning of Requests and Resources
Resources are addressed by their url and identified by a url-fragment or a (set of) query string parameters. All urls contain a version number.
When we find it necessary to introduce a change to a resource we assess if the change is a breaking change or not.
- If the change is non-breaking, we will simply make the change and it will appear in the next release without prior warning. You will be informed through the regular release notes.
- If the change is breaking, we will communicate the nature of the change along with information about how your application must adapt to the change. Such notice will include an expected earliest release data and is typically given 3 months in advance, The change will be implemented on or after the announced date, and you will be informed through the regular release notes.
If at all possible, we will provide a way for you to prepare for the change. For example:- We may create a new interface version and mark the old version as deprecated. The old version will then be retired after the grace period.
- We may make a field obsolete, and often provide another field or object to replace it. The obsoleted field will then be retired after the grade period.
What constitutes a Breaking Change?
A breaking change is one, which will break a carefully written client application.
By carefully written, we mean that your client application already is prepared to handle:
- That it receives more parameters in the response than expected.
- That the number of optional parameters on the query string is larger than expected.
- That the number of values in an enumerable has increased.
- That any field, for which we do not have a value, will not be returned in the response.
- That a service group exposes more resources than expected
- That a resource exposes more "methods" than expected.
Example
As an example consider the Accounts resource in the Portfolio Service Group.
The Portfolio Service Group currently comprises the following resources:
The Accounts resource currently supports the following request URI's:
And the Accounts Resource currently comprises a number of fields, some of which are shown below:
All of the following changes will be considered non-breaking and we may introduce them at any time:
- We add another resource the the portfolio service group. For example we introduce an "Employee" resource.
- We add another "method" to the Accounts resource. For example we introduce a "POST .../.../accounts" method, which would (potentially) allow the caller to request creation of a new account.
- We extend an existing "method" with new query string parameters. For example we add a fields="......" parameter, which allows you to specify a partial response.
- We add another field to the Accounts resource. For example we introduce a "CreatedDate" field. Note, this could both be returned in GET endpoints as well as over the streaming channel.
- We add another value to the list of possible asset types. For example we introduce an "InterestRate" asset type.