Versioning

Introduction

The Person API will roll out new versions with new functionality continuously without notice. The API uses a Major.Minor versioning scheme, and all new versions will be documented in the Changelog. Legacy versions will be available for 6 months before they are discontinued.

Targeting a specific API version

A consumer can target a specific version of the API by including a HTTP header in the request, for instance

-H "api-version: 1.6"

If this header is not included, consumers will default to use the latest version of the API.

Major and minor changes

As previously mentioned the API uses a Major.Minor versioning scheme, which will differentiate between breaking and non-breaking changes.

Major version, breaking change

When the Major version is incremented, this indicates a breaking (backwards incompatible) change to the API. A major change will force consumers to update their integration in order to target the new version. Breaking changes to the API should be rare, but might happen in cases where we are forced to make large changes to the information model, technical corrections or changes for instance to support new functionality in the API.

When a new major version of the API is released, there will be a transition phase where both the new and previous major versions will be available, and consumers will be encouraged to upgrade to the new major version within this time period.

Minor version, non-breaking change

When the Minor version is incremented, this indicates a non-breaking (backwards compatible) change to the API. New functionality to the API which are backwards compatible will be released as minor changes. Since the changes are backwards compatible, existing integrations will continue to function as before. However in most cases the consumer will need to update his integration in order to start using new features in the API. Minor changes can for instance be new API endpoints or new data points in the information model.