Client Implementation

The client module provides two classes for interacting with the Starfish API. The StarfishServer class is responsible for handling client authentication and query submission. Submitted queries are returned as AsyncQuery objects which monitor the submitted query status and return query results as they become available.

Module Contents

class starfish_api_client.client.AsyncQuery(api_url: str, headers: dict[str, str], query_id: str, verify=True)

An asynchronous query submitted to a Starfish API server

__init__(api_url: str, headers: dict[str, str], query_id: str, verify=True) → None

Instantiate a new query instance

Parameters:

• api_url – The base API server URL

• headers – Header values to use when polling for query results

• query_id – The ID of the submitted query

• verify – Require successful SSL verification

property query_id: str

Return the ID of the submitted query

async get_result_async(polling: int = 3) → dict

Return the query result as soon as it is ready

This method is intended for asynchronous use. See the get_result method for a synchronous version of the method.

Parameters:

polling – Frequency in seconds to poll the API server for query results

get_result(polling: int = 3) → dict

Return the query result as soon as it is ready

This method is intended for synchronous use. See the get_result_async method for an asynchronous version of the method.

Parameters:

polling – Frequency in seconds to poll the API server for query results

class starfish_api_client.client.StarfishServer(api_url: str, verify=True)

Class for interacting with a Starfish API server.

__init__(api_url: str, verify=True) → None

Initialize a new Server instance

Parameters:

• api_url – The Starfish API URL, typically ending in /api/

• verify – Require successful SSL verification

authenticate(username: str, password: str) → None

Authenticate against the Starfish API

Parameters:

• username – Authentication username

• password – Authentication password

Raises:

HTTPError – When the authentication request errors out or is unsuccessful

get_volume_names() → list[str]

Return a list of volume names accessible via the API server

Returns:

A list of volume names returned by the API

get_subpaths(volume_and_paths: str) → list[str]

Return a list of top level directories located under the given volume path

Parameters:

volume_and_paths – Name of the volume and path in volume:path format

Returns:

A list of directory names as strings

submit_query(**kwargs) → AsyncQuery

Submit a new API query

Valid arguments include all query-string parameters supported by the API query endpoint. See the official Starfish API documentation for more details.

Returns:

A StarfishQuery instance representing the submitted query