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.
In order to simplify interactions as much as possible, the API allows certain interactions to maintain the connection until a response is available or a timeout is reached. At the moment, this is only possible on creating sessions.
In order to enable this feature, add the HTTP
Ricloud-Await header to your request with the timeout value (current maximum of 30 seconds). For example:
All results published by the API can be encrypted using an organisation-wide public RSA key.
Any datetime attributes will always be formatted according to the ISO8601 specification. The API returns all datetime attributes with the UTC timezone. Therefore, the expected format is
The API makes use of cursor based pagination. All list type calls take the additional parameters:
limitto specify the maximum number of items to be returned. Default value is 10, max value 1000.
after_idto specify the ID from which to start listing.
before_idto 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.
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
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
Most resources are non-deletable, meaning they can only be deactivated by the owning organisation or blocked by an API administrator.