ricloud-py client implementation

The ricloud-py client is a straightforward implementation of the ricloud v3 API interface. It also includes some sample implementations of common use-cases, and some basic implementations of data retrieval from 3rd party storage buckets (AWS S3 and Google Cloud Storage).

Installation

The simplest way to get the client is to install it from PyPi.

pip install ricloud==3.0.0

You can also get the code from the GitHub repo.

Configuration

An key_token is required to authenticate against the API. If you are an existing customer, contact enterprise support to get a trial key for the ricloud v3 API.

ricloud-py can be configured in two ways:

• Via the token attribute on an imported ricloud module.

import ricloud

ricloud.token = '<your key_token>'

• Create a .ricloud.ini file in your home directory with the following content.

[api]
token = <you key_token>

See the .ricloud.ini file reference for more details.

Usage

The client exposes a class for each API resource and a set of methods to interact with them.

>>> import ricloud

>>> org = ricloud.Organisation.retrieve()

>>> print(org.name)
My Organisation

>>> org.update(name='Changed Organisation')

>>> print(org.name)
Changed Organisation

 Sample implementations

The client includes sample implementations for a number of common interactions.

These can be accessed through the samples command

iCloud

The iCloud sample implementation offers a quick way to retrieve data from an iCloud account through the command line.

Reincubate Relay

The Reincubate Relay service sample implements a set of commands needed to create a session, setup a subscription, and manually trigger polls.

Webhook endpoint

The client includes a simple webhook endpoint implementation that listens for incoming API event notifications and prints information to the console.

It is recommended to use a utility such as ngrok to safely expose your local endpoint to the internet. By default, the webhook endpoint is bound to port 8080 on your machine.

ngrok http -bind-tls=true 8080

You can see the address of your publicly exposed ngrok endpoint in the Forwarding row, like https://abcd1234.ngrok.io.

Then you can start up the listener by running the ricloud event listen command. If your client is configured correctly, it will automatically create a webhook config using the URL specified in the command and set it as the currently in-use key's default webhook config.

ricloud event listen --webhook-url https://abcd1234.ngrok.io

.ricloud.ini file reference

Section: api

token

The token used to authenticate against the API's endpoints.

url

The base url for the API. Default: https://ricloud-api.reincubate.com.

max_retries

How many times to retry a request if it fails due to a server or connection error. Default: 3

await_for

Adds the Ricloud-Await header with the specified value to enable to the await response mechanism. Default: 0

Section: webhooks

secret

The webhook config secret to use when verifying incoming event notification payloads. This is set automatically if using the --webhook-url option to the ricloud event listen command.

delta

The variance allowed between when the event was sent and when it was received, in seconds. Default: 600

Section: logging

log_level

Section: samples

output_directory

The default output directory for any results downloaded as part of a sample script. If the directory path is relative it will be created relative to the current working directory.

user_identifier

The client will create a User resource when executing sample scripts. The default value for this user's identifier is ricloud-py, but can be easily customised via this option.

This can be useful to distinguish usage between different developers within the same organisation, for example.

[api]
token = <your key_token>
url = https://ricloud-api.reincubate.com
max_retries = 1

[logging]
log_directory = logs
log_level = WARNING

[samples]
output_directory = output
user_identifier = ricloud-py