API Versioning

Introduction

The Person API follows semantic versioning principles using a Major.Minor scheme. While we continuously deploy new functionality, breaking changes are carefully managed through version control. All changes are documented in the Changelog.

Legacy versions remain available for 6 months after deprecation notice.

Version Selection

To target a specific API version, include the api-version HTTP header in your request:

api-version: 3

If no version is specified, the request defaults to the latest available version. Unless in a grace period shortly after a breaking change.

Version Types

Major Versions (Breaking Changes)

A major version increment (X.0) indicates breaking changes that require client updates. Examples include:

  • Significant information model changes
  • Technical corrections
  • Infrastructure updates
  • Security improvements

When we release a new major version:

  • Both versions run concurrently during the transition period
  • Clients have 6 months to migrate to the new version
  • Clear migration guides are provided

Minor Versions (Non-Breaking Changes)

A minor version increment (1.X) indicates backwards-compatible changes such as:

  • New endpoints
  • Additional data fields
  • Optional parameters
  • Enhanced functionality

Existing integrations continue to function without modification, though updates may be needed to utilize new features.

Migration Guidelines

Version 2 to Version 3 Migration

Required changes:

  1. Update API version header:

    api-version: 3

  2. Use updated endpoint URLs:

    • New format: /api/v3/<scope>/<method-name>
    • Old format: /api/<scope>/<method-name>

  3. Update authentication:

  4. Update scopes:

    • New: full-access and restricted-access
    • Replacing: legal-basis and no-legal-basis

**Note:** Version 2 will be deprecated in 2025.