API Versioning

Open Bank Project APIs are marked as either STABLE, DRAFT, DEPRECIATED or BLEEDING-EDGE.

You can see the current status of each version by inspecting the version_status attribute of the root endpoint e.g.:

https://apisandbox.openbankproject.com/obp/v2.0.0/root https://apisandbox.openbankproject.com/obp/v2.1.0/root https://apisandbox.openbankproject.com/obp/v2.2.0/root https://apisandbox.openbankproject.com/obp/v3.0.0/root

The latest version on develop branch is likely to be BLEEDING-EDGE.

We try to introduce a limited number of end-points per version so that each version can stabalise in a reasonable time.

Once an API version (say 1.4.0) is marked as STABLE, we won't introduce any breaking changes to it. In fact, shortly after marking a version STABLE, we "freeze" (see README) the version which will cause automated tests to fail if a developer tries to introduce changes that change the internal Scala case classes etc.

What, do we consider to be "non breaking" changes?

Which changes are allowed for a STABLE version?

Adding new optional request parameters to existing API methods.
Changing the length or format of object IDs or other opaque strings.
Changing the ResourceDoc for an endpoint (as long as this wouldn't impact the endpoint itself)
Adding an additional authorisation method for an endpoint. 

Which changes are allowed for a DRAFT version?

All of the above plus:
Changing the order of properties in existing API responses.
Adding new API resources. (This is not allowed in STABLE so that those implmenting OBP spec don't have a moving target)
Changing field names of resources

(props to Stripe for the inspiration to create a page like this)