API Versioning

Simon Redfern edited this page Jul 3, 2017 · 13 revisions

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. What, then, 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.
Adding new properties to existing API responses.
Changing the order of properties in existing API responses.
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:
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)

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.