API versioning and automatic notification of changes minimizes dependencies between you and us and eliminates the need for rollout coordination on API enhancements.

Versioning

Europace offers versioned APIs. In case of “breaking changes”, a new major version is always deployed in addition to the current version. The older version will continue to operate for at least 90 calendar days to allow our partners to plan and implement the migration to the new version.

“Breaking changes” are defined by the fact that clients must make a mandatory adjustment when using the new version.

We generally strive to keep such change as small as possible.

The versioning is realized by a URL pattern.

Example Vorgaenge-API:

• Version 1: https://api.europace2.de/v1/vorgaenge
• Version 2: https://api.europace2.de/v2/vorgaenge

If there are “breaking changes” to an API, then the version is incremented. The old version continues to run unchanged for the time being.

The version of the API is based on Semantic Versioning and has the format

MAJOR.MINOR.PATCH

and is included in the Swagger definition (info.version).

• MAJOR version is increased for API incompatible changes (e.g. new mandatory disclosures)
• MINOR version is increased in case of backward compatible API changes (e.g. new optional specifications)
• PATCH version is increased if the API remains the same, but the Swagger definition is adapted (e.g. extension or adaptation of descriptions in the API)

Note: Not all APIs are providing versioning. If not, they use different pattern to realize backward-compatibility, wich is documented on the specific API-Documentation.

Automatic change information

Europace informs about new releases of the respective APIs in the corresponding API Github repositories. Through the Github “notify” feature, you can automatically receive email notifications for new releases. This way, you will be informed about the changes to the Europace APIs automatically. We strongly recommend enabling this notification for the APIs in production use.