Versioning¶

This document describes the allowed ways of changing an existing API.

There are three different ways to change the API:

Backward compatible ➜ API version does not changed.
Representation of resource(s) changes ➜ minor version number increase.
A resource changes behavior ➜ major version number increase.

1. Backward compatible changes¶

The following changes are considered backward compatible:

Add a new field to a JSON object.
Change order of fields in a JSON object.
Add a new link in the _link section.
Add a new field in the _embedded section.

(Note: these guidelines use the word field instead of the word member from the JSON specification.)

The following applies to backward compatible changes:

Clients MUST be assumed to cope with backward compatible changes¶

Clients should be liberal in what they accept and conservative in what they send.

Do not remove fields when it will be replaced by another field¶

In case a new field will replace another field, the old field MUST stay around until the version changes (see section 2. Resource representation changes). The field that will be removed MAY be deprecated.

Deprecation example:

{
  "_links": {
     "self": { "href": "/v1/categories/92" },
     "describedby": { "href": "https://api.platform.com/v1/docs/categories" },
     "https://api.platform.com/v1/docs/rels/parent-category": { "href": "/v1/categories/91" }
  },
  "name": "Alpha romeo",
  "short-name": "Alpha romeo",
  "shortName": "Alpha romeo",
  "_deprecation": {
    "short-name": "https://api.platform.com/v1/docs/resources/category/short-name-deprecation"
  }
}

Old links MAY be deprecated when it will be replaced with a newer version¶

In case a link replaces an older link, the old link MUST stay around until the version changes (see section 2. Resource representation changes). The link that will be removed MAY be deprecated. The HAL specification describes how to deprecate a link. (See HAL and our deviations for links to the specification.)

Before:

{
    "_links": {
        "self": { "href": "/" },
        "describedby": { "href": "https://api.platform.com/v1/docs" },
        "https://api.platform.com/v1/docs/resources/categories": { "href": "/v1/categories" }
    }
}

After (in this example tags will replace categories):

{
    "_links": {
        "self": { "href": "/" },
        "describedby": { "href": "https://api.platform.com/v1/docs" },
        "https://api.platform.com/v1/docs/resources/categories": {
          "href": "/v1/categories",
          "deprecation": "https://api.platform.com/v1/docs/resources/categories/deprecation"
        },
        "https://api.platform.com/v1/docs/resources/tags": { "href": "/v1/tags" }
    }
}

The deprecation attribute value of the link relation MUST point to a developer document that describes when and why the relation is deprecated.

2. Resource representation changes¶

Changing the representation of a resource in a non-backward compatible way SHOULD NOT happen often, perhaps once a year.

The base URL MUST change as follows:

https://host/base-url/v1 ➜ https://host/base-url/v1.1 (no minor version yet)
https://host/base-url/v1.1 ➜ https://host/base-url/v1.2 (minor version increased)

Notes:

The base URL for all resources MUST change at the same time, also for resources that did not change.
All references (inside the resources) MUST use the updated base URL.
The old version MUST be available for a grace period. The grace period is RECOMMENDED to be 6 months.

Side notes:

To keep an older version available there are basically 2 options:
- Support resources on old URL and new URL in the same implementation.
- Keep an old version of the implementation deployed separately on the old URL.
Consequence of this mechanism is that URLs identify resource representations, not resources. This is a conscious departure of REST principles.

3. Resource behavior changes¶

Changing the behavior of your resources SHOULD only be used as a last resort.

The base URL MUST change as follows:

https://host/base-url/v1 ➜ https://host/base-url/v2 (no minor version yet)
https://host/base-url/v1.1 ➜ https://host/base-url/v2 (major version increased, no minor version)