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¶
Requests to the server can be in application/json, and some endpoints accept as well multipart/form-data. Responses are always JSON, and in case of a failure, the server response is a JSON with the following fields:
Field | Required | Description |
exception | no | Error code, for example: ValidationError , FaceNotFoundError , etc.
|
message | no | A message providing more information about what went wrong. The message may be free and not specified for certain error types. |
FIELDNAME | no | Missing or mistaken fields on a POST request. Each field will be an item in the dictionary. |
Example:
{
"exception": "FaceNotFound",
"message": "Unable to locate a face in the image"
}
Validation errors (requests with missing or badly-formed fields) will be returned with a 400 HTTP status code and as a dictionary where field names are keys and values are arrays of strings with messages related to errors on the corresponding field. These messages won’t contain ‘exception’ or ‘message’ fields in the response. In the following documentation, these messages will be indicated as ValidationError in the following.
Some of the objects returned by this API can be paginated, i.e., they are queried and returned in paginated format. This format indicates the current page (page), the number of objects per page (perPage), the total number of pages (numPages) and the total number of objects (count). Additionally, this format also indicates the type of objects that are paginated. The paginated array will be formed by items of a particular resource, and the name of the array is the type of resource in plural. Then, paginated responses are JSON based with the following fields:
Field | Required | Description |
page | yes | Current page. |
perPage | yes | Number of items per page. |
numPages | yes | Number of pages in total. |
count | yes | The total number of items, so numPages = count / perPage |
ARRAYNAME | yes | Name of the array, for instance, in the case of galleries it is ARRAYNAME=galleries |
This paginated responses will be documented by indicating the ARRAYNAME value and the content of just one of the array items.
The following example shows page 1 of paginated Gallery objects where each page may contain up to 10 galleries. The total amount of galleries being paginated is 5 so the total number of pages is 1.
Example:
{
"page": 1,
"perPage": 10,
"numPages": 1,
"count": 5,
"galleries": [
{
"galleryId": "58da7427-cf42-487a-ab6b-0d2717c3c492",
…,
},
{
"galleryId": "20a6e6f7-a3d9-4ffb-959c-72b45f1b01f4",
…,
}
]
}
Runtime Errors¶
Here is a list of the runtime errors that may occur when using the das-FaceBond API. These errors are returned as JSON objects with the following fields:
UnableToRetrieveIdentificationError¶
{
"error": "Unable to Retrieve Identification",
"message": "Unable to retrieve identification with uuid: 1234567890",
"status_code": null
}
- Description: This runtime error may occur when attempting to retrieve a specific identification but encountering difficulties or failures in the process.
GalleryFacesNotUpdatedError¶
{
"error": "Gallery Faces Not Updated",
"message": "Gallery faces are not updated with gallery model",
"status_code": null
}
ModelInconsistencyError¶
{
"error": "Model Inconsistency",
"message": "Model inconsistency between gallery and identification",
"status_code": null
}
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.