SSIN - Pull report RESTful service.
Overview
Client technical documentation to consume the biometrica-reports-service.
If a correct payload request is send to this service, an application/octet-stream file stream will be retrived as a response, otherwise an application/json response will be served.
Service Endpoints
List of available URL endpoints with port and protocol.
Using a standard connection and common ports as 80 (http) or 443 (https), such port can be omitted, ex: http://theurl.com:80/ or https://theurl.com:443/ becomes http://theurl.com/ or https://theurl.com/.
| Type | URL | Port | Protocol |
|---|---|---|---|
|
|
443 |
HTTP SSL (https) |
|
|
|
443 |
HTTP SSL (https) |
|
Warning
|
As July 1st, 2019 PROD has not been released to the public. |
Security
The webservice enforces the following security policy:
-
https Protocol interchange.
-
RSA 2048 bits (e 65537) / SHA256withRSA
-
TLS 1.2
-
TLS_RSA_WITH_AES_256_GCM_SHA384
|
Important
|
A client’s consumer must implement the security specification to be able to connect. |
Authentication
Only authorized clients are able to consume this webservice, clientKey and accessKey pairs are provided per client and per environment.
A clientKey and accessKey parameter must be added to the header request, ex:
curl -i -k -H "Accept: application/json" -H "Content-Type:application/json" -H "clientkey:Phsfwee5eipae2mec23e2dxdas" -H "accessKey:wdE3eN8xajosdkWEJAn28dhblkas"Request Parameters
The webservice uses only the http POST method for all requests. Authentication credentials must be sent in every request, the following is the minimal header submission:
| Header Paramenter | Content |
|---|---|
|
|
application/json |
|
|
application/json |
|
|
Unique identification string. |
|
|
Unique identification key string. |
The POST body must be an application/json string with exactly the following parameters:
| Paramenter | Content |
|---|---|
|
|
csv or json. As of July 1st, 2019 only csv are available. |
|
|
charge or arrest. |
|
|
Desired date of the report, format yyyy-MM-dd. All events for the given date are retrieved from 00:00:00 UTC 000 to 23:59:59 UTC 000, this date is when it first appeared on the system. |
Ex:
{"reportFormatType":"csv", "eventType":"arrest", "date":"2017-01-01"}'HTTP status codes
This webservice adheres as closely as possible to standard HTTP and REST conventions in its use of HTTP status codes.
| Status code | Usage |
|---|---|
|
|
The request completed successfully and an application/octet-stream response is provided, a consumer client has to convert this stream in a file format or ingest directly. |
|
|
The request has been accepted for processing, but the processing has not been completed. An application/json response is generated, possible reasons include: "Report has not been created yet", "Format is not valid", among others. |
|
|
The client credentials sent were invalid or expired. |
|
|
The request was malformed. |
|
|
The requested resource did not exist. This usually happens when an incorrect endpoint is given. |
|
|
The client is sending too many requests in a very short period of time, by default in a DEV environment a maximum of 1 request per second is allowed, in PROD a maximum of 1 request every 10 seconds is allowed. This restriction is based on the client’s ip address (ipv4 or ipv6). |
Errors
Whenever an error response is returned, the body will contain a JSON object that describes the problem. The error object has the following structure:
| Param | Description |
|---|---|
|
|
Timestamp of the event in format yyyy-MM-dd’T’HH:mm:ss.SSSZ ex: 2001-07-04T12:08:56.235-0700 |
|
|
Integer NNN, standard http status code. |
|
|
Standard http status description. |
|
|
Description of the event. |
|
|
Service endpoint relative to the URL, ex: /reportRequest. |
Ex:
{"timestamp":"2019-07-01T18:41:33.052+0000","status":202,"error":"Accepted","message":"Report has not been created yet: [reportFormatType=csv, eventType=charge, date=2025-01-01]","path":"/reportRequest"}