Menu

For Developers

Versioning Policy

 

Before we dive into specific details, it’s useful to recall what our overriding goal is. It is much easier to update a server than all the clients that might talk to it, therefore the fundamental goal of careful evolution of any ReST API is:

    Old clients must work against new servers

To make this maxim practical, clients need to follow the simple rule:

    Ignore any unexpected data in the interaction with the server

In particular, clients can never assume that they have a complete picture of what they will find in a response from the server.Specifically clients should be lenient if they discover unexpected properties in returned resource representations.

Versions and Backwards Compatibility

We distinguish two types of API change:

Minor Changes

  • Fixing a bug so that a request which resulted in an error response before is now successful
  • The change is the only way to fix a high priority security defect
  • Adding new resources
  • Adding support for new HTTP methods on existing resources
  • Adding new data representation formats on existing resources
  • Adding new properties or elements to an existing resource representation
  • Adding new response headers
  • Adding optional request parameters (or changing a mandatory request parameter to be optional)
  • Adding optional request headers (or changing a mandatory request header to be optional)
  • Adding optional properties (or changing mandatory properties to be optional) to resource representations which may be supplied by clients
  • Changing an error message in a response to better reflect the error that occurred

Significant Changes

  • A change such that a request which was successful before now results in an error response (unless the success reported previously was hiding an existing error condition)
  • Changing or removing resource URIs
  • Changing or removing a property in a resource representation
  • Changing the semantics of a property in a resource representation which may be supplied by clients
  • Changing or removing a response header
  • Changing which response status code is returned
  • Removing support for HTTP methods on existing resource URIs
  • Adding mandatory request parameters
  • Adding mandatory request headers
  • Adding mandatory properties to resource representations which may be supplied by clients
  • Changing HTTP protocol i.e. HTTP to HTTPS

Version 1 of the API is considered stable. We intend only to make Minor Changes to it, and these sparingly (essentially, to fix bugs.)

Version 2 of the API is under active development. Minor Changes will be made regularly and without notice. For Significant Changes, we will make our best effort to contact API users and make them aware of the change ahead of time.