Polls

A poll resource contains information on a specific request for data. Once a poll is created, it will trigger the creation of one or more tasks in order to complete the request.

Attributes

Tasks

The most important role of the pol resource is to reflect the progress of its associated tasks and allow the end-user to start fetching results from these as soon as they become available. Therefore, the poll resource exposes three task related attributes wherein associated tasks are categorised by their state.

States

The state of a poll reflects only whether the poll is awaiting initialisation (pending), is in progress (processing), or all tasks have finished execution (completed).

A poll does not reflect any error states other than through its associated tasks.

Payload

Depending on a source's service, a poll may need a payload for the request to be configured fully.

For example, an info type poll requires a payload which specifies the info_types attribute.

{
  "info_types": []
}

In this case we leave the brackets empty to ask for all available info types.

Another example, a data type poll requires a payload which specifies which data types to retrieve.

{
  "data_types": ["photos.backup", "messages.sms", "messages.whatsapp"]
}

While a files type poll requires the identifiers of the files to be retrieved.

{
  "files": ["icpl://xyz123", "icpl://abc321"]
}

More complex polls can then be composed using a variety attributes.

Create POST /polls

Create a poll for data against a specific session.

As a session resource is already directly tied to a specific source, you do not have to provide the source parameter. However, it can be provided to specify that the poll target a child source of the primary source the session is tied to. For example, on the iCloud service a session can only be created against iCloud account sources (the primary source of the iCloud service), but you can target data only from a specific iCloud backup (a child source of the iCloud account) by providing its ID.

Using cURL

curl https://ricloud-api.reincubate.com/polls \
  -X POST \
  -H 'Authorization: Token <your key_token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "session": "<session ID>",
  "type": "data",
  "payload": {
    "data_types": ["info.account"],
  }
}'

Using ricloud-py

import ricloud

poll_payload = {
  'data': ['info.account'],
}

poll = ricloud.Poll.create(
  session='<session ID or ricloud.Session instance>',
  type='data',
  payload=poll_payload,
)

Retrieve GET /polls/{poll ID}

Using cURL

curl https://ricloud-api.reincubate.com/polls/<poll ID> \
  -H 'Authorization: Token <your key_token>'

Using ricloud-py

import ricloud

poll = ricloud.Poll.retrieve(<poll ID>)

List GET /polls

Using cURL

curl https://ricloud-api.reincubate.com/polls \
  -H 'Authorization: Token <your key_token>'

Using ricloud-py

import ricloud

polls = ricloud.Poll.list()