dacadoo Models

Usage

dacadoo model APIs are provided as RESTful APIs using JSON.

Requests

Requests must be authenticated using an API key. The API key is passed in the X-dacadoo-Key header. The following is an example of such request:

POST /risk/1 HTTP/1.1
Host: https://prod.models.dacadoo.com/api
X-dacadoo-Key: 8VqwwA6NvKs5UC2BT4dXYedgXIrdfitMyh7QVDaQ
Content-Type: application/json; charset=UTF-8

{ "years": 10, "mhm": { ... } }

Please refer to the documentation of each model for the required request body.

Please note that the dacadoo models do not allow passing the API key as a query parameter because this often leads to the key being stored in log files, thus compromising its security.

Response

If the request is successful, the platform responds with a 200 OK status, and a response body provided in JSON format. For example:

200 OK
Content-Type: application/json; charset=UTF-8
X-dacadoo-Quota: interval=minute; count=1; limit=50; next=1530008580, interval=day; count=1; limit=10000; next=1530057600

{ "years": 10, "risks": { ... }, "mhm": { ... } }

Again, please refer to the documentation of each model for the provided response body.

If the request is unsuccesful, the platform responds with an error status code and response body. Common error status codes are these.

400 Bad Request. This indicates a problem with the request. Client developers should review the documentation of the respective model.
429 Too Many Requests. A rate limit has been exceeded. Clients must wait before sending another request. See below.
500 Internal Server Error. An error occurred when processing the request. Client developers should contact dacadoo.

Errors include an error response body as follows:

400 Bad Request
Content-Type: application/json; charset=UTF-8
X-dacadoo-Quota: interval=minute; count=1; limit=50; next=1530008580, interval=day; count=1; limit=10000; next=1530057600

{
  "error": "bad_request",
  "error_description": "missing field 'years'"
}

Rate Limits

The dacadoo models are rate limitted. Rate limits can apply on minute, day, and month intervals.

The X-dacadoo-Quota header shown above provides information for each rate limit (interval) regarding the number of requests performed in the current interval (count), the maximum number of requests allowed (limit), and the start time of the next interval (next) where the time is expressed as seconds since 1970-01-01T00:00:00Z.

In case a rate limit is exceeded, the platform responds with a 429 Too Many Requests error status. Client programs must be written carefully as not to "hammer" the dacadoo server infrastructure in case this happens. Rather, client programs must be designed to wait until requests are available again.

429 Too Many Requests
Content-Type: application/json; charset=UTF-8
X-dacadoo-Quota: interval=minute; count=50; limit=50; next=1530008580, interval=day; count=50; limit=10000; next=1530057600

{
  "error": "too_many_requests",
  "error_description": "limit exceeded"
}