API Versions

Versioning of the REST API

The konfipay REST API is stabilized through version numbers to ensure long-term compatibility of integrations. Changes to an API can affect existing implementations when so-called breaking changes occur. To handle such cases in a structured way, versioning is applied exclusively through whole major versions.
The version is part of the URL and is specified in the form

api/{version}/endpoint

For example:

api/v2/bank-accounts

It is the responsibility of the API consumer to decide which version to use and when to switch to a newer version. Older versions remain available for a defined period of time, allowing migrations to be planned accordingly. Deprecations of versions are announced early, typically more than one year before final shutdown.

Criteria for a new version

A new major version (e.g., v1 → v2) is released only when breaking changes occur. Breaking changes in particular include:

• Removal or renaming of fields in messages (JSON/XML)

• Changes to enumerations or other fixed value ranges

• Modification or removal of URLs

• Removal or renaming of URL parameters

• Change of a field’s data type (e.g., int → string)

• Introduction of new mandatory fields or modification of default values

• Changes to the semantics or business logic of existing fields (e.g., if a field amount previously contained the gross amount and now contains the net amount)

• Adjustments to HTTP status codes (e.g., previously 200, now 204)

Changes without a new version

The following adjustments are not considered breaking changes and can be introduced within an existing version:

• Adding new URLs (e.g., additional endpoints)

• Adding new optional URL parameters

• Extending requests with optional fields

• Extending responses (e.g., additional fields that clients may ignore)

Note on client implementation

When implementing clients, it should be ensured that changes without a new version number do not cause incompatibility. In particular, extensions of responses are unproblematic as long as clients are tolerant towards unknown fields and ignore them rather than treating them as errors.

Version history