Changelog Policy
At shyftplan, our commitment is to provide you with a seamless and consistent API experience. To ensure that your integrations continue to function smoothly and are enriched with new features and improvements, please be informed about our API update policy.
Non-breaking changes ensured via versioning
We are not introducing breaking changes (i.e., modifications that disrupt existing integrations that are implemented in line with our documentation). For this, it is important to understand the types of API endpoint changes we distinguish and how these are handled with versioning.
Types of API endpoint changes we distinguish:
- Major changes: Changes that could impact existing integrations like removal or modification of existing endpoints, or changing the format of data.
- Minor changes: Changes such as adding new fields or new optional parameters.
How API endpoint changes are handled with versioning to ensure they are non-breaking:
- Handling of major changes:
- Each endpoint of our API is versioned, i.e., it has one or more versions, each reachable at its own URL (e.g., “
.../api/v1/xxx”, “.../api/v2/xxx”, …). - Every major change that could affect current integrations will be released as a new version of an API endpoint. This means, it is reachable under a new URL (e.g., “
.../api/v2/xxx” if the previous version was reachable at “.../api/v1/xxx”). At the same time, we keep the previous version of the endpoint live in parallel. This means, you can keep using the old version of the endpoint unchanged. - Old versions of API endpoints will be supported for a specified duration (at least 12 months or longer) after the introduction of a new version.
- Each endpoint of our API is versioned, i.e., it has one or more versions, each reachable at its own URL (e.g., “
- Handling of minor changes: Changes that are not altering the behaviour of an endpoint will be rolled out as part of the current API endpoint version, i.e., not result in a new version number of that endpoint.
For clarification: It is important to note (and also adheres to standard JSON specification) that the order of properties within JSON objects is not fixed and can change at any time. However, properties are consistently organized under the object to which they belong, ensuring that the structure remains logical and intuitive, and can thus be processed in an unchanged manner. This approach allows for flexibility and the seamless integration of new features, while maintaining a coherent and predictable hierarchy within the JSON responses. Additions (new properties) may appear in the JSON response without prior notice.
Deprecated version of an endpoint
When an endpoint is deprecated, it means it will be removed in a future release. We will provide ample notice before its removal. Deprecated endpoints will be supported for a minimum period (at least 12 months) after deprecation notice.
How to handle multiple endpoint versions
Always integrate with the "latest" version of a specific API endpoint as it will be supported longest. Frequently visit our developer portal for any updates or changes and ensure to subscribe to our update notifications.
Communication
We maintain a changelog on our developer portal where you can view updates of our API endpoints (link). Our integration partners have the opportunity to sign up for any changes of our API changelog (link).
Feedback & support
Your feedback on our API and any potential improvements is invaluable. Please reach out with your insights. For technical support or clarifications regarding updates, contact our support team ([email protected]).
Emergency updates
In rare cases, we might roll out emergency updates to address security or critical functional issues. Such updates might not adhere to the standard notice periods, but we'll strive to communicate them ASAP.