πŸ—Ί OverviewΒΆ

IntroductionΒΆ

There are four services that comprise and are used to interact with the ricloud API: asmaster, asapi, aschannel and asstore. Clients generally only interact with two of these services rather than all four.

The API can be controlled in one of two ways: with asmaster or asapi. Results are received from aschannel (a firehose stream for real-time retrieval of data) or asstore (a bucket for batch retrieval of data).

Component Results delivery Best suited for Token management
asmaster aschannel Regular retrieval of data Reincubate
asapi aschannel or asstore Infrequent low-volume access Deferred to client

Real-time data accessΒΆ

With asmaster, clients register interest accounts or devices, then receive new data on a stream in real-time when it becomes available. asmaster is effectively a smart controller for asapi, which further reduces a client’s need to understand the mechanics of data storage and retrieval, and which can provide data more rapidly and safely then a client can with their own implementation against asapi.

Depending on the underlying datatype and source, asmaster either subscribes internally to an upstream feed of data for real-time updates, or uses a smart predictive scheduler to manage polling.

Near-time & batch data accessΒΆ

With asapi, clients request data from accounts or devices as and when they want it, then receive data when it is ready on a stream or by polling a bucket.

Concepts & servicesΒΆ

The ricloud API is modeled around four key concepts: actions, tasks, services and accounts.

Actions are the basic unit of work performed by the API; each action is associated to a service. For example, one could perform the fetch_data action, part of the icloud service. Every action is performed against an account. Accounts represent end-user accounts for whichever service data is being retrieved from. An account is accessible to a client if it has been registered by that client. Each instance of an action is described as a task, and allocated a task_id.

App stream master (asmaster)ΒΆ

asmaster is a subscription control mechanism for the API. It enables users to:

  • Discover services, actions and endpoints they are authorized to use
  • Register, deregister and learn about accounts
  • Subscribe and unsubscribe to automatic feeds of data from accounts

With this approach, asmaster automatically generates tasks for asapi, and resulting data obtained from aschannel.

Note

Detailed documentation for asmaster is available at subscribing for data with asmaster.

App stream API (asapi)ΒΆ

asapi is an asynchronous control mechanism for the API. It enables users to:

  • Discover services, actions and endpoints they are authorized to use
  • Register, deregister and learn about accounts
  • Submit asynchronous tasks
  • Query the status of tasks

Once completed, data from tasks can be obtained from either aschannel or asstore, depending on the client’s use-case.

Note

Detailed documentation for asapi is available at requesting data with asapi.

App stream channel (aschannel)ΒΆ

aschannel is a streaming endpoint, which allows clients to retrieve the results of each submitted task, in real-time, as they are generated.

Results are retrieved by opening a connection to the aschannel endpoint.

  • Results are streamed in JSON format
  • As soon as they become available they can be retrieved from the service
  • The channel is stateless; if a client misses transmission of a result, it cannot be replayed without resubmission of the task

Note

Detailed documentation for aschannel is available at streaming data with aschannel.

App stream storage (asstore)ΒΆ

asstore is a time-limited result store, which allows clients to retrieve the results of submitted tasks as and when they become available.

  • Results are stored for a limited period before being expired and deleted
  • A result may only be downloaded once; it is deleted once consumed

Note

Detailed documentation for asstore is available at downloading data with asstore.

Standards usedΒΆ

Throughout ricloud and its documentation, the following standards are used:

  • The API consistently uses dates in the ISO-8601 format, in the UTC timezone. For example, 24th December would be expressed as 2014-12-24 17:30:00.000000.
  • Structured data returned by ricloud‘s components always use JSON. This is invariably indicated by the application/json content-type in responses.
  • Command examples in this documentation are given in bash format, using the curl command.