Straker Translation is always looking to improve our API. There will be occasions when we release a change or a new version of our API and you are required to adjust your integration. This page outlines examples of what we would consider to be breaking changes, a non-breaking change and communicating the time period to update to a new version of the API.
Breaking Change
A breaking change can potentially cause a disruption to other applications using the API.
These are the types of changes that we consider breaking:
- Changing the functionality of an endpoint
- Removing an allowed parameter, request field, or response field
- Adding a required parameter, request field, or response field
- Introducing a new validation
- Changing a non-required parameter to required
Non-breaking changes
A non-breaking change should not cause any disruption to applications using the API. We recommend designing your API implementation to accommodate these changes.
Non-breaking changes include:
- Adding new endpoints
- Adding new methods to existing endpoints
- Adding new fields – new fields in responses, new optional request fields or parameters, new required request fields with default values
- Adding a new value returned for an existing text field
- Changing the order of fields returned within a response
- Adding an optional request header
- Removing a redundant request header
- Changing the length of data returned within a field
- Changing the overall response size
- Changing error messages
- Fixes to HTTP response codes and error codes from incorrect code to correct code
Communicating API changes
For any breaking API changes, we will send a notification to the email address associated with a API access token at least 14 days prior to the release.
Versioning Changes
When we release a new version, previous versions will be generally phased out over a period time, normally a year. We will notify account holders of the time period for phasing out previous versions of the API.