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 authentication method is API key based

All requests must include the apikey authorization header provided by Veridas for using its services.

Should you have more than one Verisaas cloud account, please ensure that you use the appropriate credentials for the service you are looking to manage their authentication APIKEYs or IP allow list. For instance, you cannot use credentials from vali-Das service to manage the authentication APIKeys or IP allow list of das-Peak service.

Also, ensure that every query to keymaker service is sent from a registered IP address on the cloud account you are trying to manage.

Requests¶

The content-type header must be used on every request with the "json" value
The API is HTTP-based and uses TLS everywhere with valid certificates. For security reasons, customers should never trust VeriSaaS endpoints exposing invalid certificates
The service includes an /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 will be encoded using JSON. Responses will return a suitable HTTP status code indicating if the request was successful (200/201 or 204 if nothing else is returned) or not (any other code). Responses will also include a code field in the JSON body that can provide more information about the specific error on each case.

In general, successful responses will have the following formats:

HTTP Status: 200 OK

{
    "items": [
        {
        {"field": "value1"},
        {"field": "value2"}
        }
]
}

or

HTTP Status: 200 OK

{
"field": "value1",
"field": "value2"
}

or

HTTP Status: 204 NO CONTENT where:

Field	Required	Description
items	no	Message payload. It will contain a JSON content defined by each endpoint.

In case of error:

Field	Required	Description
code	yes	Error code
message	no	A message indicating what went wrong

Example:

{
    "code": "InvalidCredentials",
    "message": "Invalid authentication credentials"
}

Versioning¶

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

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

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

i.e. for the sandbox environment:

GET https://api-work.eu.veri-das.com/keymaker/v1/alive