Best practices (v2)

Updated

General

There are a number of best practices for use to make the most of the Reincubate Cloud Data API.

  • Make use of this documentation. Many of the common questions are answered in these materials, and the documentation is regularly updated.
  • The API status page can be used to sign up for updates on any planned or emergency API maintenance.
  • Clients that take advantage of a Slack integration channel tend to go live sooner.
  • The Open Source client provides a full example of an integration with the ricloud service, and examining that (or re-using code from it) can save a lot of work during the integration.
  • Take advantage of the mock data when testing and integration, but bear in mind that real data access can be slower.
  • Follow security and privacy best practice, and do not store end-user credentials. Instead, use the tokenisation system.
  • Don't hard-code the task submission or results endpoints in requests: whilst they may often take the same value, the API may vary them from time to time.
  • Don't generate more tasks than are necessary: for instance, polling for backup updates is unnecessary more than a few times per day, and a lot can be done to devise an accurate schedule for this. The API is capable of completing a large number of tasks and generating a lot of data in a small amount of time, and in particular when using aschannel, clients should be wary of requesting more than they can readily consume.
  • Reincubate considers it a best practice to directly contact account holders at such times as their accounts are first accessed, and then on an ongoing basis to ensure that they are informed client activity. See enhancing privacy for more details.
  • Clients with requirements to regularly poll accounts should evaluate asmaster rather than asapi.

🚨 Support and service status

Service status & maintenance notices

Reincubate maintains a status page at status.reincubate.com. The status pages allows users to subscribe to updates. Updates are sent for any planned or emergency maintenance.

Direct support

Client support is available by email at ent-support@reincubate.com and via private Slack integration channels. Clients can contact the support team to arrange setup of the integration channel.

Reporting issues

When encountering issues with the API, it can speed resolution if the support team are informed of the X-RI-Build HTTP header received in the problem response. The X-RI-Build HTTP header looks like this:

X-RI-Build: 1.0-pre-ios9-395-g126226b; nj-api-7

When triaging issue reports, the support engineers will invariably ask for the curl commands that can be used to demonstrate replication of the issue, and for the server's response.

🔓 Minimising iCloud account locking

Apple locks iCloud accounts with a variety of frequencies based on a large and dynamic set of criteria. Broadly, these fall into three categories:

  1. The way in which a piece of technology communicates
  2. The nature of the infrastructure used to communicate
  3. The rhythm, patterns and frequency with which that technology communicates

Reincubate's Cloud Data API addresses all three as they evolve. The first is handled by the proprietary code behind the API, and the second by the substantial and complex infrastructure stack that Reincubate maintain. However, when directly controlling the API with asapi, clients may struggle to manage #3 at scale or in use-cases that require regular polling.

Light or one-off use with asapi is unlikely to lead to locking, but regular access may do if not properly managed. The asmaster service is designed to manage this for clients, and is recommended over direct asapi access for these use-cases.

🎁 Mock data for integration & testing

Apple iCloud service sample data

A rich mock account of Apple iCloud service data is provided under the john.appleseed@reincubate.com account, which is accessible with the password joshua. The data is provided in order to rapidly test integrations with the API.

Access to this account is not billable, and the sample data is delivered directly from Reincubate's servers, significantly accelerating the response time.

FAQ

Does the API store any feed or file data?

No, not when used with aschannel, as feed and file data is streamed to clients and not persisted in the RI stack. When using asstore, information is stored in buckets until retrieved. However, the channel is recommended for almost all use-cases.

In some cases the API will persist some metadata, most notably where asmaster's scheduler retains a rolling window of metadata to help it calculating accurate polling windows.

How do I request feeds and attachments with asmaster?

There is no need to. Once subscribed to accounts or devices, data will be provided automatically via aschannel as and when it is ready.

How do I tell asmaster to give me more or fewer modules?

There is no need to do anything programmatically. A client's key configuration includes data on which modules they have access to, and all modules will be used when streaming data. Once the provisioning team have updated a client key, the new module-set will be reflected in feeds.

What frequency does asmaster poll with?

asmaster's scheduler mechanism strives provide data subject to two aims: not exceed the best-practice polling frequency for a given service, and providing data as close to when it is made available as possible. The scheduler will always prioritise not harming the account or violating best-practice over getting fresh data.

When operating with real-time data, this can mean data is provided with real-time, near-time or batch frequency. With batch data, the scheduler will itself work in batch mode.

The ruleset behind frequency selection is dynamic.

What limits are set on a trial key?

Trial key limits can vary according to the nature of the key. They may be limited by:

  • Number of devices or accounts accessible via the key
  • Support for non-2FA/2SV accounts (eg. trial users can be prevented from accessing non-2FA accounts for compliance reasons)

Where is the API hosted?

See the note in hosting and connectivity.

Why am I not seeing any data for data type xyz?

If you are seeing an empty response from the ricloud, and not an error, it means that the data source was empty. To make sure data is available and ready for ricloud to retrieve, try steps listed below.

  1. Make sure that the associated setting for the data type is turned on.

    • For data types where the source is an iOS device backup, this means turning on iCloud backups in Settings > [user name] > iCloud > iCloud Backup > iCloud Backup and making sure the device has been backed up at least once. A backup can be triggered manually by pressing the Back Up Now button on the aforementioned screen.
    • For realtime and near-time data types, the settings tend to be more specific to the service responsible for syncing the data with iCloud. For example, the setting associated with Find My iPhone can be found under Settings > [user name] > iCloud > Find My iPhone > Find My iPhone. The associated setting is listed alongside other data type properties in the feed modules section.
  2. Make sure the device gets opportunities to sync data.

    • For iCloud backup based feeds, the device needs to be plugged-in and locked to begin an automatic iCloud backup. You can still trigger a manual backup at any time.
    • For realtime and near-time data types, sync triggers vary depending on the service design. In general, it can take around 4-6 hours for some of the slower sync processes to run.

Deprecation

  • As of Q1 2017, the legacy ricloud 1.x can be considered deprecated, although it is still fully supported by virtue of an adapter which reshapes and routes its traffic to asapi.

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:35 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.