MUST NOT break backward compatibility within a version [57]

Non- breaking changes include:

• Adding response parameters
• Adding new endpoints
• Adding non- required request parameters

APIs only need to be up-versioned when a breaking change is made. Breaking changes include:

• a change in the format of the response data for one or more calls
• a change in the response type (i.e. changing an integer to a float)
• renaming fields and/or resource paths
• removing any part of the API.

Breaking changes should always result in a change to the major version number for an API or content response type.

Breaking changes are allowed when the API has not been deployed to production. If the API has any consumers, align the changes with the teams.

SHOULD avoid multiple versions [58]

We recommend to avoid multiple versions of the same API as much as possible and change your API’s in a backwards compatible way. Multiple versions can significantly complicate understanding, testing, maintaining, evolving, operating and releasing our systems.

SHOULD allow a 6 month grace period when deprecating [59]

API providers should allow a 6 month grace period when deprecating. The corresponding schema should be like:

paths:
  '/{locationId}':
    get:
      deprecated: true

The deprecated attribute is not shown in the developer portal. Therefor update either the description of the API or the description of the API operation to also mention its deprecation.

MUST version business objects [83]

Like the APIs the business objects are semantically versioned because objects can be referred to from any number of other business objects and API specifications. This means when breaking changes, such as renaming or removing attributes are introduced, the business should get a new major version and a new file. The new version will (temporarily) coexist with the old version of the business object until all reference to the old object are removed.