Backwards Compatibility
To successfully build an application that uses the GoNow API, you need to understand the API's versioning and release process. The GoNow API team strives to make upgrades straightforward and to comply with the Principle of Least Astonishment.
Versioning Model
The GoNow API follows the Navitaire DCS release cycle. Each version of the GoNow API corresponds to a specific version of the underlying Navitaire DCS platform. Backward compatibility is maintained between patch releases within the same minor version. For example, if your application was built and tested against GoNow API version 1.2.0, it will remain fully compatible with version 1.2.1 without requiring any changes on your side.
Please let the GoNow API team know through your contact point if you observe any breaking changes during an upgrade.
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 to authorization requirements (e.g., changing from using bearer tokens to OAuth)
- Removing enumeration values
- Endpoints that restrict or filter data compared to their previous behavior
- Anything that would violate the Principle of Least Astonishment
- Anything that would force a client application developer following best practices to update their application
What is Not a Breaking Change?
- Adding a new endpoint
- Adding a new version of an existing endpoint (e.g.,
GET /api/dcs/v1/passengers→GET /api/dcs/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 GoNow 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 development.
When Does the GoNow API Make a Breaking Change?
In the case of a security issue, the GoNow API team 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 GoNow API endpoints. In this case, a new version of the endpoint is created and the original version is deprecated. Deprecated endpoints will include a Deprecated response header indicating the deprecation status.
