Requesting data with asapi (v2)

Updated

asapi is an asynchronous control mechanism for the ricloud 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 the aschannel or the asstore, depending on the client's use-case.

Methods at a glance

Service, action and endpoint discovery

/account/

Using the /account/ endpoint, clients can obtain information on:

  • Available services
  • Available actions and their parameters and permissions
  • Endpoints available for task submission and retrieval

To do so, a discovery request is made:

$ curl \
    -X GET \
    -H 'Authorization: Token <TOKEN>' \
    https://asapi.reincubate.com/account/ -D -

This will return a set of JSON describing the available services, actions and endpoints. The example below is abbreviated:

{ "services": [{
    "name": "iCloud",
    "actions": [{
      "description": "",
      "parameters": [{
        "type": "string",
        "description": "",
        "optional": false,
        "name": "Device",
        "slug": "device"
      }, {
        "type": "date",
        "description": "",
        "optional": true,
        "name": "Since",
        "slug": "since"
      }],
      "name": "Fetch Data",
      "execution": "Asynchronous",
      "slug": "fetch-data",
      "permissions": {
        "data": ["sms"]
      }
    }],
    "slug": "icloud"
  }],
  "task_submission_endpoint": {
    "host": "asapi.reincubate.com",
    "protocol": "https",
    "uri": "/submit-task/"
  },
  "stream_endpoints": [{
    "host": "aschannel.reincubate.com",
    "protocol": "https",
    "uri": "/stream/"
  }]
}

In this case, the client would have access to the icloud service and the fetch-data action. They would need to submit device and data parameters when using it, and optionally also since.

This last data parameter must be in list format; this parameter can contain any values listed in the permissions > data of the fetch-data section.

The task_submission_endpoint is defined in this response, and it informs clients where actions may be submitted for execution.

The stream_endpoint in the example above is defined as aschannel.reincubate.com, which means that aschannel is configured as the results endpoint. Alternatively, this could direct clients to asstore, depending on the configuration of their token.

Account registration and deregistration

register-account

In order to submit actions, we need to inform asapi of the accounts that may have actions performed against them. To do so, we will use the /register-account/ endpoint:

$ curl \
    -X POST \
    -H 'Authorization: Token <TOKEN>' \
    -d "service=<SERVICE>" \
    -d "username=<USERNAME>" \
    https://asapi.reincubate.com/register-account/ -D -

In this request, <SERVICE> is service which owns the specific action, whereas <USERNAME> represents for the account which will be used in the actions.

deregister-account

If an account is not to be used any further, it can be deregistered. To deregister an account, a similar request can be sent to the /deregister-account/ endpoint:

$ curl \
    -X POST \
    -H 'Authorization: Token <TOKEN>' \
    -d "service=<SERVICE>" \
    -d "username=<USERNAME>" \
    https://asapi.reincubate.com/deregister-account/ -D -

Both methods, on success, will return a 200 response with

{ "success": true
}

Possible errors include:

  • unique_together: "Account with this Service, Client and Username already exists"

Task submission

[TASK-SUBMISSION]

Asynchronous tasks can be submitted using the endpoint specified in task_submission_endpoint.

To submit a task, the following command is used:

$ curl \
    -X POST \
    -H "Authorization: Token <TOKEN>" \
    -d "service=<SERVICE>" \
    -d "action=<ACTION>" \
    -d "account=<ACCOUNT>" \
    -d "param1=<VALUE1>" \
    -d "param2=<VALUE2>" \
    <TASK_SUBMISSION_ENDPOINT> -D -

On that request:

  • <SERVICE> and <ACTION> represent the target service and action
  • <ACCOUNT> refers to a previously registered account
  • param1, param2 and subsequent parameters form the specific payload of the task, requirements for which are described by the service, action and endpoint discovery method

On success, the request will return a 200 with:

{ "task_id": "<TASK_ID>",
  "retrieval_protocol": "<RETRIEVAL_PROTOCOL>",
  "stream": "<STREAM>",
  "success": true
}

In these responses: <TASK_ID> provides an ID for the task which can be used to query its status and to retrieve the task's result, if using the asstore <RETRIEVAL_PROTOCOL> indicates the method used to retrieve the task's results and can take the value of aschannel or asstore <STREAM> is stream ID for use in retrieving the task's results, if using the aschannel*

If the request was malformed, the "success" property will be false and the response will include an "errors" section with feedback. For example:

{ "errors": {
    "service": [
      ["[u'Invalid service name']", "invalid_service"]
    ]
  },
  "success": false
}

Possible errors include: * invalid_service: 'Invalid service name' * invalid_parameter_value: 'Value not permitted for parameter' * no_such_account: 'No such account' * invalid: 'Invalid value' * limit_exceeded: 'Too many task IDs submitted' * invalid_action: 'Invalid action' * missing-param: 'Parameter is missing'

Querying task statuses

/task-status/

For each task submitted to the asapi endpoint, a task_id is provided. The client can periodically submit this task_id to the asapi endpoint in order to discover a task's status. Its status can be queried with a POST request on the /task-status/ endpoint. Clients may request the status of up to 10,000 tasks simultaneously.

$ curl \
    -X POST \
    -H "Authorization: Token <TOKEN>" \
    -d "task_ids=<TASK_ID_1>,<TASK_ID_2>,<TASK_ID_3>,<TASK_ID_4>,<TASK_ID_5>,<TASK_ID_6>,<TASK_ID_7>" \
    https://asapi.reincubate.com/task-status/

Given at least one correct <TASK_ID>, the response will be a 200 in this format:

{ "<TASK_ID_1>": {
    "status": "<TASK_STATUS>",
    "retrieval_protocol": "<RETRIEVAL_PROTOCOL>",
    "result_retrieved": "<RETRIEVAL_STATUS>",
    "success": "<TASK_SUCCESS>"
  },
  "success": "<CHECK_SUCCESS>"
}

If <TASK_SUCCESS> is "True", then the results are immediately available at the appropriate endpoint.

The status property can take the following values:

  • Pending
  • In progress
  • Work complete
  • Publish ongoing, with result available
  • Publish complete (in this case, the success value be "true")
  • Publish failed (in this case, the success value be "false")
  • Task did not complete successfully. (in this case, the success value be "false")

<RETRIEVAL_PROTOCOL> indicates the method used to retrieve the task results and can take the value of aschannel or asstore depending on the token.

<RETRIEVAL_STATUS> is a boolean, indicating whether the task's results have already been consumed by a client. If <RETRIEVAL_STATUS> is "True", then the results have already been consumed and are no longer available.

The <CHECK_SUCCESS> parameter located at the root of the JSON tree refers to the success of status checking itself. If this is "false", the response will contain an additional "errors" entry.

Possible errors include:

  • invalid: "Invalid task_id value: "
  • limit_exceeded: "Too many task ids submitted, limit is "

An example of output is shown below:

{
  "<TASK_ID_1>": {
    "success": false,
    "error": "No task with this ID was found."
  },
  "<TASK_ID_2>": {
    "status": "Publish complete",
    "retrieval_protocol": "aschannel",
    "result_retrieved": false,
    "success": true
  },
  "<TASK_ID_3>": {
    "status": "Publish complete",
    "retrieval_protocol": "asstore",
    "retrieval_endpoint": "https://asstore.reincubate.com/fetch/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/",
    "result_retrieved": true,
    "success": true
  },
  "<TASK_ID_4>": {
    "status": "Publish failed",
    "retrieval_endpoint": "https://asstore.reincubate.com/fetch/1111111-2222-3333-4444-555555555555/",
    "success": false,
    "error": "Task did not complete successfully.",
    "retrieval_protocol": "asstore",
    "result_retrieved": false
  },
  "<TASK_ID_5>": {
    "status": "Pending",
    "result_retrieved": false,
    "success": false
  },
  "<TASK_ID_6>": {
    "status": "In progress",
    "result_retrieved": false,
    "success": false
  },
  "<TASK_ID_7>": {
    "status": "Work complete",
    "result_retrieved": false,
    "success": false
  },
  "success": true,
}

How can we help?

Our support team are here to help!

Our office hours are Monday to Friday, 9am to 5pm GMT.

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

Get in touch › 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.