4. API client objects¶

API client objects provide direct access to the rerobots API with several useful features like mapping returned data into other types.

4.1. Example¶

import rerobots.api

apic = rerobots.api.APIClient()

wdeployments = apic.get_wdeployments()
print(apic.get_wdeployment_info(wdeployments[0]['id']))

4.2. Create a new client object¶

class rerobots.api.APIClient(api_token=None, headers=None, ignore_env=False, base_uri=None, verify=True)¶

Instantiate API client.

api_token is some auth token obtained from https://rerobots.net/tokens In general this token has limited scope and might not be sufficient for some actions that this API client will try to do, leading to the exception WrongAuthToken.

headers is a dictionary of headers to add to every request made by this client object. This is only of interest in special use-cases.

ignore_env determines whether configuration data should be obtained from the process environment variable REROBOTS_API_TOKEN. Default (ignore_env=False) behavior is to try REROBOTS_API_TOKEN if api_token is not given.

base_uri is the string prefix used to create API requests. In general the default value works, but special cases might motivate changing this, e.g., to use an unofficial proxy.

verify determines whether the TLS certificates of the server are checked. Except possibly during testing, this should not be False.

4.3. Workspace deployments¶

APIClient.get_wdeployments(query=None, maxlen=None, types=None, page=None, max_per_page=None)¶

Get list of workspace deployments.

types, if given, should be a list of workspace types (str). The significance of parameters is described in the HTTP-based API documentation.

The parameters page and max_per_page can be used for pagination, which restricts the maximum number of items in the list of instances returned in any one response. Cf. documentation of the HTTP API.

APIClient.get_wdeployment_info(wdeployment_id)¶: Get details about a workspace deployment.

4.4. Instance creation and management¶

APIClient objects provide methods for working with instances. All operations are associated with an API token.

Note that classes presented in Workspace instances abstract some of the methods of APIClient and provide combined operations, e.g., copying a file to an instance via ssh.

APIClient.get_instances(include_terminated=False, page=None, max_per_page=None)¶

Get list of your instances.

The parameters page and max_per_page can be used for pagination, which restricts the maximum number of items in the list of instances returned in any one response. Cf. documentation of the HTTP API.

APIClient.get_instance_info(instance_id)¶

Get details about a workspace instance.

This operation requires sufficient permissions by the requesting user.

APIClient.request_instance(type_or_wdeployment_id, sshkey=None, vpn=False, reserve=False, event_url=None, duration=None)¶

Request new workspace instance.

If given, sshkey is the public key of the key pair with which the user can sign-in to the instance. Otherwise (default), a key pair is automatically generated.

If reserve=True, then create a reservation if the workspace deployment is not available at the time of this request.

APIClient.get_vpn_newclient(instance_id)¶: Create new OpenVPN client.

APIClient.terminate_instance(instance_id)¶: Terminate a workspace instance.

4.5. add-on: cam¶

The cam add-on provides access to cameras in the workspace through the rerobots API.

APIClient.get_snapshot_cam(instance_id, camera_id=0, coding=None, dformat=None)¶

Get image from camera via cam add-on.

If coding=None (default), then returned data are not encoded. The only coding supported is base64, which can be obtained with coding=’base64’.

If dformat=None (default), then the image format is whatever the rerobots API provided. Currently, this can be ‘jpeg’ or ‘ndarray’ (i.e., ndarray type of NumPy).

Note that some coding and format combinations are not compatible. In particular, if dformat=’ndarray’, then coding must be None.

4.6. add-on: mistyproxy¶

The mistyproxy add-on provides proxies for the HTTP REST and WebSocket APIs of Misty robots.

APIClient.activate_addon_mistyproxy(instance_id)¶

Activate mistyproxy add-on.

Note that this add-on is unique to workspaces that involve Misty robots, e.g., https://help.rerobots.net/workspaces/fixed_misty2fieldtrial.html

When it is ready, proxy URLs can be obtained via status_addon_mistyproxy().

APIClient.status_addon_mistyproxy(instance_id)¶

Get status of mistyproxy add-on for this instance.

The response includes proxy URLs if any are defined.

APIClient.deactivate_addon_mistyproxy(instance_id)¶

Deactivate mistyproxy add-on.

Note that a cycle of deactivate-activate of the mistyproxy add-on will create new proxy URLs.

Note that calling this is not required if the workspace instance will be terminated.