API Client

APIClient is a class for handling requests to the Civis API. An instantiated APIClient contains a set of resources (listed below) where each resource is an object with methods. By convention, an instantiated APIClient object is named client and API requests are made with the following syntax:

client = civis.APIClient()
response = client.resource.method(params)

The methods on APIClient are created dynamically at runtime by parsing an collections.OrderedDict representation of the Civis API specification. The methods are generated based on the path and HTTP method used with each endpoint. For example, GET /workflows/1 can be accessed with client.workflows.get(1). GET endpoints that don’t end in a parameter use a list method instead. Below are examples of endpoints and how they map to API Client methods:

Endpoint API Client Method
GET /workflows client.workflows.list()
GET /workflows/1 client.workflows.get(1)
GET /workflows/1/executions client.workflows.list_executions(1)
PATCH /workflows/1 client.workflows.patch(1, ...)
POST /workflows/1/executions client.workflows.post_executions(1)
GET /workflows/1/executions/2 client.workflows.get_executions(1, 2)

Note that Python’s built-in help function can be used to see lists of available endpoints for a resource (e.g., help(client.workflows)) or to get documentation for a specific endpoint function (e.g., help(client.workflows.list)). The ? operator in IPython (e.g., ?client.workflows) and the shift-tab hotkey in a Jupyter notebook also cause documentation to be displayed.

By default, the Civis API specification specification is downloaded from the /endpoints endpoint the first time APIClient is instantiated (and cached in memory for the remainder of the program’s run). In some circumstances, it may be useful to use a local cache of the API specification rather than downloading the spec. This can be done by passing the specification to the client through the parameter local_api_spec as either the collections.OrderedDict or a filename where the specification has been saved.

api_key = os.environ['CIVIS_API_KEY']
spec = civis.resources.get_api_spec(api_key)

# From OrderedDict
client = civis.APIClient(local_api_spec=spec)

# From file
with open('local_api_spec.json', 'w') as f:
    json.dump(spec, f)
client = civis.APIClient(local_api_spec='local_api_spec.json')
class civis.APIClient(api_key=None, return_type='snake', retry_total=6, api_version='1.0', resources='all', local_api_spec=None)[source]

The Civis API client.

Parameters:
api_key : str, optional

Your API key obtained from the Civis Platform. If not given, the client will use the CIVIS_API_KEY environment variable.

return_type : str, optional

The following types are implemented:

retry_total : int, optional

A number indicating the maximum number of retries for 429, 502, 503, or 504 errors.

api_version : string, optional

The version of endpoints to call. May instantiate multiple client objects with different versions. Currently only “1.0” is supported.

resources : string, optional

When set to “base”, only the default endpoints will be exposed in the client object. Set to “all” to include all endpoints available for a given user, including those that may be in development and subject to breaking changes at a later date. This will be removed in a future version of the API client.

local_api_spec : collections.OrderedDict or string, optional

The methods on this class are dynamically built from the Civis API specification, which can be retrieved from the /endpoints endpoint. When local_api_spec is None, the default, this specification is downloaded the first time APIClient is instantiated. Alternatively, a local cache of the specification may be passed as either an OrderedDict or a filename which points to a json file.
Attributes:
aliases

An instance of the Aliases endpoint

announcements

An instance of the Announcements endpoint

clusters

An instance of the Clusters endpoint

credentials

An instance of the Credentials endpoint

databases

An instance of the Databases endpoint

endpoints

An instance of the Endpoints endpoint

enhancements

An instance of the Enhancements endpoint

exports

An instance of the Exports endpoint

files

An instance of the Files endpoint

git_repos

An instance of the Git_Repos endpoint

groups

An instance of the Groups endpoint

imports

An instance of the Imports endpoint

jobs

An instance of the Jobs endpoint

json_values

An instance of the Json_Values endpoint

match_targets

An instance of the Match_Targets endpoint

media

An instance of the Media endpoint

models

An instance of the Models endpoint

notebooks

An instance of the Notebooks endpoint

notifications

An instance of the Notifications endpoint

ontology

An instance of the Ontology endpoint

predictions

An instance of the Predictions endpoint

projects

An instance of the Projects endpoint

queries

An instance of the Queries endpoint

remote_hosts

An instance of the Remote_Hosts endpoint

reports

An instance of the Reports endpoint

scripts

An instance of the Scripts endpoint

search

An instance of the Search endpoint

services

An instance of the Services endpoint

storage_hosts

An instance of the Storage_Hosts endpoint

tables

An instance of the Tables endpoint

templates

An instance of the Templates endpoint

users

An instance of the Users endpoint

workflows

An instance of the Workflows endpoint

Methods

get_aws_credential_id(self, cred_name[, owner]) Find an AWS credential ID.
get_database_credential_id(self, username, …) Return the credential ID for a given username in a given database.
get_database_id(self, database) Return the database ID for a given database name.
get_storage_host_id(self, storage_host) Return the storage host ID for a given storage host name.
get_table_id(self, table, database) Return the table ID for a given database and table name.
default_credential

The current user’s default credential.

get_aws_credential_id(self, cred_name, owner=None)

Find an AWS credential ID.

Parameters:
cred_name : str or int

If an integer ID is given, this passes through directly. If a str is given, return the ID corresponding to the AWS credential with that name.

owner : str, optional

Return the credential with this owner. If not provided, search for credentials under your username to disambiguate multiple credentials with the same name. Note that this function cannot return credentials which are not associated with an owner.
Returns:
aws_credential_id : int

The ID number of the AWS credentials.
Raises:
ValueError

If the AWS credential can’t be found.

Examples

>>> import civis
>>> client = civis.APIClient()
>>> client.get_aws_credential_id('jsmith')
1234

>>> client.get_aws_credential_id(1111)
1111

>>> client.get_aws_credential_id('shared-cred',
...                              owner='research-group')
99
get_database_credential_id(self, username, database_name)

Return the credential ID for a given username in a given database.

Parameters:
username : str or int

If an integer ID is given, this passes through directly. If a str is given, return the ID corresponding to the database credential with that username.

database_name : str or int

Return the ID of the database credential with username username for this database name or ID.
Returns:
database_credential_id : int

The ID of the database credentials.
Raises:
ValueError

If the credential can’t be found.

Examples

>>> import civis
>>> client = civis.APIClient()
>>> client.get_database_credential_id('jsmith', 'redshift-general')
1234

>>> client.get_database_credential_id(1111, 'redshift-general')
1111
get_database_id(self, database)

Return the database ID for a given database name.

Parameters:
database : str or int

If an integer ID is given, passes through. If a str is given the database ID corresponding to that database name is returned.
Returns:
database_id : int

The ID of the database.
Raises:
ValueError

If the database can’t be found.
get_storage_host_id(self, storage_host)

Return the storage host ID for a given storage host name.

Parameters:
storage_host : str or int

If an integer ID is given, passes through. If a str is given the storage host ID corresponding to that storage host is returned.
Returns:
storage_host_id : int

The ID of the storage host.
Raises:
ValueError

If the storage host can’t be found.

Examples

>>> import civis
>>> client = civis.APIClient()
>>> client.get_storage_host_id('test host')
1234

>>> client.get_storage_host_id(1111)
1111
get_table_id(self, table, database)

Return the table ID for a given database and table name.

Parameters:
table : str

The name of the table in format schema.tablename. Either schema or tablename, or both, can be double-quoted to correctly parse special characters (such as ‘.’).

database : str or int

The name or ID of the database.
Returns:
table_id : int

The ID of the table.
Raises:
ValueError

If a table match can’t be found.

Examples

>>> import civis
>>> client = civis.APIClient()
>>> client.get_table_id('foo.bar', 'redshift-general')
123
>>> client.get_table_id('"schema.has.periods".bar', 'redshift-general')
456
username

The current user’s username.