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
Version 3
In version 3, use new urls to choose version. It is optinal to set api-version
in HTTP header for version 3.
Version < = 2
To target a specific API version from 2 or under, include the api-version
HTTP header in your request:
api-version: 2
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:
Update API version header:
api-version: 3
Use updated endpoint URLs:
- New format:
/api/v3/<scope>/<method-name>
- Old format:
/api/<scope>/<method-name>
- New format:
Update authentication:
- Implement DPoP authentication
- See: DPoP Authentication Guide
Update scopes:
- New:
full-access
andrestricted-access
- Replacing:
legal-basis
andno-legal-basis
- New:
See Change log for more details on other changes.
**Note:** Version 2 will be deprecated in 18.12.2025 in production and 1.10.2025 in test.