Open API versioning policy

The API is a continuous project. Over time, new features, and new information will be added to the API.

What is an API change?

The API will have minor and major changes. For minor changes, functionality is added, either in new calls, or as additional information in responses. These changes can happen several times a year. Major changes are changes that modify the existing signature of API calls, and are not backwards compatible. With the release of a major change, usually several minor changes will be released as well.

Versions and Numbering

Minor changes will be numbered in documentation as minor versions (e.g., 3.1). They will be announced in the documentation and release notes, but are not included in the path. Major changes will be numbered as major releases, and will be included in the path. A major releases will be defined as a “v” followed a sequential number, which increases with each new version of the protocol/domain (e.g, ../v4/..). In addition, every release will be documented in release notes.

Backwards compatibility

Every time a new major version is released, the older version will be supported for a designated period of time, with a minimum of 6 months. When older versions are phased out, API users will be notified several months prior this event.