Skip to content

Considerations

The following are some general considerations about this API that must be taken into account before consuming the service.

Compatibility

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

The following changes are considered 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 maximum length of existing opaque string properties with documented conflicting constraints

Backwards incompatible (breaking) changes may be introduced by bumping the API version, as explained on the Versioning section. In this scenario, previous versions of the API may be marked as deprecated and stop receiving new features. Should 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 (also called sunsetting) to ensure that users have enough time to migrate to the newest version of the API without causing any downtime or service disruptions.

Authentication

The service has an OAuth layer that manages the credentials to use the API. This layer is implemented by the Authorization header (Authorization: Bearer TOKEN).

The Application is initialized with a token which does not expire, associated to the user "admin" which is also created by default. This token, as well as the "admin" password and the rest of the credentials needed to use the API (oauth application client_id and client_secret) are: * onprem installations: displayed on the screen along the rest log lines during the docker containers initialization stage * cloud instance: provided at the time of delivering the service.

Requests

  • The form-datacontent type must be used on every request.
  • The API is HTTP-based and uses SSL with valid certificates.
  • Endpoints attempt to conform to the design principles of Representational State Transfer (REST).
  • The service includes a GET /aliveendpoint that returns the 204 HTTP status code if the service is up and running. This can be used to check the service’s health.

All responses are encoded using JSON, regardless of the accepted content-type specified by the client. Responses return a suitable HTTP status code indicating if the request is successful (20X) or not (any other code). Error responses include a message and a code field in the JSON body that provide more information about the concrete error on each case.

In general, successful responses have the following format:

HTTP Status: 200 OK

{
    "data": {
        DATA
  }
}

or

HTTP Status: 204 NO CONTENT

where:

Field Required Description
data no Message payload. It will contain an arbitrary JSON content defined by each endpoint.

In case of API error:

Field Required Description
code yes Error code
message no A message indicating what went wrong
errors no A list of the errors providing more information.

In case of OAuth authentication error:

Field Required Description
detail yes A message indicating what went wrong

Versioning

The API version will be included in the URL, after the base url and before the endpoint:

https://<base_url>/<service>/v{number:integer}/<endpoint>

Non backwards compatible changes will cause a version increment. As of now, the API only supports the v1 version.