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
tokenattribute on an importedricloudmodule.
import ricloud
ricloud.token = '<your key_token>'
- Create a
.ricloud.inifile 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