Backwards Compatibility
To successfully create an application that uses the Digital API, the Digital API team's versioning and release process need to be understood. The Digital API team strives to make upgrades straightforward and to comply with the Principle of Least Astonishment.
Each version of the Digital API is intended for one minor version of New Skies. For example, New Skies 4.6.0 will have a corresponding 4.6 version of the Digital API. Backward compatibility for the Digital API is defined as the compatibility between two versions matching the minor version. In the example earlier, Digital API 4.6.2 would be fully compatible with a client application written and tested with Digital API 4.6.1. If upgrading from Digital API 4.6.1 to 4.6.2, the Digital API ensures that there are no intentional breaking changes being introduced. The Digital API team has policies and many automated tests in place to ensure that upgrades within minor releases of the Digital API have as little impact on users as possible.
Please let the Digital API team know through your Customer Service Delivery Manager if there are any breaking changes that were observed.
What is a breaking change?
- Removing endpoints or parameters
- Renaming endpoints or parameters
- Changes in behavior for an existing endpoint
- Changes in error and response codes (i.e., HTTP status codes)
- Changes in request/response parameter data types (e.g., changing a parameter from a string to an integer, changing a parameter from a single value to an array)
- Changes in media types (e.g., changing from application/json to application/xml)
- Modifying an optional request parameter to a required one
- Modifications on authorization requirements (e.g., changing from using bearer tokens to OAuth)
- Removing enumeration values
- Endpoints that restrict or filter data compared to its previous behavior
- Anything that would violate the Principle of Least Astonishment
- Anything that would force a UI developer following best practices to update their application
Further Reading
- https://nordicapis.com/what-are-breaking-changes-and-how-do-you-avoid-them/
- https://docs.github.com/en/rest/about-the-rest-api/breaking-changes?apiVersion=2022-11-28
What is not a breaking change?
- Adding a new endpoint
- Adding a new version of an existing endpoint (e.g., GET api/nsk/v1/passengers → GET api/nsk/v2/passengers)
- Adding an optional request parameter (non-required)
- Adding a new response parameter
- Changes to string-based error messages (e.g., Passenger not valid → Passenger first name is not valid)
Client applications of the Digital API must be flexible enough to handle additive and non-breaking changes. It is especially important to design applications to ignore new response parameters, as these are commonly added as part of feature requests.
When does the Digital API need to make a breaking change?
In the case of a security issue, the Digital API will assess that a breaking change is necessary to eliminate a vulnerability. If a breaking change is made intentionally, we will provide all necessary details on this portal.
About deprecated endpoints
There are certain circumstances where a new feature requires breaking changes to published Digital API endpoints. In this case, a new version of the endpoint is created and the original version is deprecated.
