API Versioning
In order to ensure that the REST API for TrustX can evolve and improve as required, the REST API for TrustX is versioned. If and when a breaking change needs to be applied, then a new version of an API will be published.
The following API changes are considered to be backwards-compatible:
- The addition of new operations.
- The addition of new optional request parameters to existing APIs.
- The addition of new optional request HTTP headers to existing APIs.
- The addition of new fields to existing API responses.
- The addition of new enumerated values to API responses.
- The addition of new response HTTP headers to existing API responses.
- The change in order of fields for existing API responses.
- Changes in length of fields such as error messages and error strings.
- The addition of new error codes and/or updates to validation logic.
Default values may be applied by the server where new optional parameters, HTTP headers or fields are expected. In this case the new default value is applied to ensure that the operation performs as before.
The following API changes are not considered to be backwards-compatible. The changes would constitute a breaking change and will require the publication of a new API:
- The removal or renaming of an operation.
- The removal, addition or renaming of a required request parameters.
- The removal, addition or renaming of required HTTP headers.
- The removal, addition or renaming of any required field the request.
- The change of semantics to any request parameter, HTTP header or field within the request body.
- The removal of any previously supported enumerated value
- Changes to authentication or authorization requirements.
Backwards Compatible Clients
To ensure that any API clients remain backwards compatible, the following rules should be applied:
- Unknown fields within response bodies should be ignored.
- Unknown HTTP headers should be ignored.
- Applications should not rely on the order of fields within response bodies.
Resource/rate limiting
Resource and rate limits are not considered part of the API and may change.
Deprecation of APIs
If any API is deemed to to be unnecessary, unmaintainable, outdated or unsafe then they may be marked as deprecated. An API or part of an API shall be marked as depreciated when removed or replaced in a newer API. Notice of intent to deprecate shall be provided in order to give those with integrations opportunity to migrate to the newer API. Deprecated APIs shall be supported for the given notice period after such time support for the deprecated API shall be removed.
If you use TrustX APIs directly within an application, such as a mobile application, then you need to ensure that your users perform updates before the end of the deprecation period. This may mean that you will have to update well ahead of any deprecation deadlines in order to provide your users with sufficient times to update. You may also need to consider the concept of 'forced updates' for users who have not updated with in the update period to ensure your users do not suffer any loss of service.