OpenAPI

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 it it will appear in the next release on Simulation without prior warning. You will be informed through the regular release notes, which accompany any new release.
  • If the change is breaking, we will create a new interface version and mark the old version as deprecated. We will also communicate a grace period (typically 3 months) after which the old interface version will be retired. The new interface will again appear in the next release on Simulation without prior warning. You will be informed through the regular release notes, which accompany any new release.

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 Users Resource in the Portfolio Service Group.

The Portfolio Service Group currently comprises the following resources:

The Users resource currently supports the following request URI's: 

And the User Resource currently comprises the following fields:

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 users resource. For example we introduce a "users/{userid}/loginhistory" method.
  • 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 users resource. For example we introduce an "email" field.
  • We add another value to the list of possible asset types. For example we introduce an "InterestRate" asset type.