Protocols

Updated

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

Coming Soon!

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:

Ricloud-Await: 10

Encrypted publishing

Coming Soon!

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

Attribute types

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 "2018-08-22T10:25:05Z".

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.

How can we help?

Our support team are here to help!

Our office hours are Monday to Friday, 9 AM to 5 PM GMT. The time is currently 5:58 AM GMT.

We aim to reply to all messages within one working day.

Go to support section › Contact the enterprise team ›
Our awesome support team

© 2008 - 2019 Reincubate Ltd. All rights reserved. Registered in England and Wales #5189175, VAT GB151788978. Reincubate® is a registered trademark. Privacy & terms. We recommend 2FA. Built with in London.