Skip to content

Compatibility policy

This service exposes a RESTful API designed to be backwards-compatible (whenever possible). An API is said to be backwards-compatible if a client written against a previous version of the API will keep working against future ones.

The following changes are considered backwards compatible:

  • Adding new resources (on new URIs)
  • Adding new optional request form fields or JSON properties
  • Adding new optional query parameters
  • Adding new JSON properties to existing API responses
  • Changing the order of JSON properties on existing API responses
  • Changing the order of items on JSON object or array properties (unless the documentation states they are ordered)
  • Adding new optional headers in requests
  • Adding new headers in responses

We consider the following changes backwards incompatible (breaking changes):

  • Removing API resources
  • Renaming API resources (changing URIs)
  • Adding new required request form fields, JSON properties, query parameters or headers
  • Making any existing optional request form fields, JSON properties, query parameters or headers required
  • Removing existing request form fields, JSON properties, query parameters or headers
  • Changing the meaning of existing request form fields, JSON properties, query parameters or headers
  • Adding new request form fields, JSON properties, query parameters or headers that alter the meaning of existing ones
  • Changing the type of existing request form fields or JSON properties (from string to number for example)
  • Changing the format or increasing the maximum length of existing opaque string properties with documented conflicting constraints

Backwards incompatible (breaking) changes may be introduced by bumping the API version. In this scenario, previous versions of the API may be marked as deprecated and stop receiving new features. If this happen, these old versions will be available for some agreed period of time, until they are eventually removed.

Veridas will announce in advance this deprecation and removal process to ensure that users have enough time to migrate to the newest version of the API without causing any downtime or service disruptions.