API Lifecycle and Versioning

To provide our partners and customers with the best possible product experience we continuously improve our services. Thus API changes are inevitable. Occasionally we may have to deprecate or sunset APIs for various reasons such as security changes, legislative requirements, performance considerations, redundancy, or other important reasons. We understand that breaking changes require additional effort on your part. Therefore, we aim to minimize breaking changes and provide assistance throughout the change process.

API Lifecycle Stages

Stage	Description
`Not Active`	Endpoints that are not yet available.
`Beta`	Endpoints can change anytime (including breaking changes), with or without notification to API consumers.
`Active`	Stable endpoints with ongoing support for all kinds of fixes and new features. Breaking changes may occur in very rare cases.
`Deprecated`	Endpoints are still available for API consumers, but there is no active maintenance except for severe security issues.
`Sunset`	Deprecation period ended and API endpoints are no longer available.

Beta

We’ll mark all API endpoints in this phase accordingly in our documentation.
APIs in this stage can be changed anytime, with or without notice.
Feedback to those endpoints is highly welcome and can be given via the existing communication channels (Slack or E-Mail).

Active

We may add new, non-breaking functionality to active APIs and you can opt in to these enhancements. By non-breaking, we mean e.g. adding non-mandatory fields.
We'll inform you of updates or improvements to active APIs through regular release notes.
We may make breaking changes to active API endpoints, such as deprecating certain fields or making them mandatory. In this case, we'll follow our deprecation guidelines as stated below.

Deprecated

We’ll mark all API endpoints in this phase accordingly in our documentation and suggest alternatives if possible.
We'll give at least six months' notice if we make breaking changes like removing features or adding mandatory fields.
We may give less than six months' notice for security, legal, or third-party reasons!
Pliant won't be liable for risks associated with using deprecated APIs.

Important remarks

We do our best to inform you about new features as well as about new non-breaking and breaking changes by providing a regularly updated changelog. In case of breaking changes, we additionally contact you proactively to align and support.

API Versioning

You can set an additional HTTP header (Pliant-API-Version) when using our API to request a specific API version. When this header is set and you request an API version which is either active (i.e. the current one) or deprecated but not yet sunset, we will respond to your request accordingly with the appropriate data structure of this API version.

Pliant-API-Version: 2.0.0

Pliant-API-Version: 2.1.0