Protocols

Asynchronous processing

The API makes use of asynchronous processing for all polls. This includes interactions with external services, such as the iCloud, as these can take seconds or minutes to complete depending on the amount of processing required.

A number of standard resource interactions can trigger asynchronous 'side effects' which are outlined in the API reference documentation. These are typically to perform validity checks or other utility functions.

The asynchronous foundation of the API also helps simplify the interface for periodic polling which are triggered from within the API. This means event and result retrieval is the same whether interacting with the API directly or through scheduled polls.

Await response

The API supports awaiting the completion of asynchronous tasks via long-lived requests to minimise the need for polling and reduce the total response time for end-users. To enable this functionality, add the Ricloud-Await HTTP header to your requests with the desired timeout value. The current maximum timeout value is 10 seconds.

Ricloud-Await: 3

This functionality is supported on the following endpoints:

• Create session POST /sessions
• Test storage config POST /configs/storage/{storage_config ID}/test
• Test webhook config POST /configs/webhook/{webhook_config ID}/test

Encrypted publishing

All results published by the API can be encrypted using an organisation-wide public RSA key.

End-user trials

An end-user trial module is available for client use. This can be used to return a "teaser" of data to potential end-users. The module provides a feed of the last five messages along with a last location and a summary count of other available messages.

Using this mechanism can be more cost-effective than using a full key for end-user trials.

Analytics and reporting

The ricloud's iCloud service provides a number of additional features around analytics and reporting.

Two modules are available for enterprises: basic app usage, which shows which apps were used on an iOS device within a given day, and advanced app usage, which provides further information including number of sessions, duration of sessions, and so on. More information on these modules is available on request.

Forensics and recovery

Forensic undeletion and recovery functionality is available for a number of modules as indicated below, including the Messages (SMS, MMS and iMessage) and iCloud Photo Library modules.

Reincubate have a number of custom forensic tools which can be applied on request to other modules, including WhatsApp and WeChat.

Attribute types

Datetime

Datetime attributes are formatted according to the ISO8601 specification. The API returns all datetime attributes with the UTC timezone, i.e. "2018-08-22T10:25:05Z".

A number of resource listing endpoints allow filtering on datetime attributes, such as date_created. To filter using more useful operators, prefix the datetime filter value with one of lt_, lte_, gt_, or gte_.

Timedelta

Attributes of the timedelta type are always in seconds unless otherwise specified.

Pagination

The API makes use of cursor based pagination. All list type calls take the additional parameters:

• limit to specify the maximum number of items to be returned. Default value is 10, max value 1000.
• after_id to specify the ID from which to start listing.
• before_id to specify the resource ID from which to stop listing.

List responses include returned resources under the data attribute. Also included is the helper attribute has_more which signals if more resources can be listed which were not included due to the limit.

Rate limits

Requests to the API can be limited either by a standard rate limit or by an in-flight requests limit. The former is used to minimise abuse of API resources at scale, while the latter is used to protect individual resource instances.

Rate limit example: the number of requests to the API from a single organisation is capped at 10,000 requests per hour. This helps protect against malicious or accidental spikes in traffic.

In-flight limit example: an instance of a source resource cannot have a task created against it if another task is already processing. This maintains session integrity, minimises traffic to external services, and

Versioning

Though the major releases of the API follow a largely semantic versioning scheme (i.e. v1, v2, v3), any changes done within the v3 version of the API are versioned following a calendar versioning scheme (i.e. 2018-11-06). The version can be set globally for your organisation or specified per request via the Ricloud-Version header.

Deletable resources

Most resources are non-deletable, meaning they can only be deactivated by the owning organisation or blocked by an API administrator.