APIClient is a class for handling requests to the Civis API.
APIClient contains a set of resources
(listed below) where each resource is an object with methods. By convention,
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. By default, this specification is downloaded from
/endpoints endpoint the first time
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
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')
APIClient(api_key=None, return_type='snake', retry_total=6, api_version='1.0', resources='base', local_api_spec=None)¶
The Civis API client.
api_key : str, optional
Your API key obtained from the Civis Platform. If not given, the client will use the
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.
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.
announcements An instance of the
apps An instance of the
clusters An instance of the
codes An instance of the
credentials An instance of the
databases An instance of the
endpoints An instance of the
enhancements An instance of the
exports An instance of the
files An instance of the
groups An instance of the
imports An instance of the
jobs An instance of the
match_targets An instance of the
media An instance of the
models An instance of the
notebooks An instance of the
notifications An instance of the
ontology An instance of the
predictions An instance of the
projects An instance of the
queries An instance of the
remote_hosts An instance of the
reports An instance of the
results An instance of the
scripts An instance of the
search An instance of the
tables An instance of the
templates An instance of the
users An instance of the
workflows An instance of the
The current user’s default credential.
Find an AWS credential ID.
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.
aws_credential_id : int
The ID number of the AWS credentials.
If the AWS credential can’t be found.
>>> 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
Return the credential ID for a given username in a given database.
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.
database_credential_id : int
The ID of the database credentials.
If the credential can’t be found.
>>> import civis >>> client = civis.APIClient() >>> client.get_database_credential_id('jsmith', 'redshift-general') 1234
>>> client.get_database_credential_id(1111, 'redshift-general') 1111
Return the database ID for a given database name.
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.
database_id : int
The ID of the database.
If the database can’t be found.
Return the table ID for a given database and table name.
table : str
The name of the table in format schema.table.
database : str or int
The name or ID of the database.
table_id : int
The ID of the table. Only returns exact match to specified table.
If an exact table match can’t be found.
The current user’s username.
- API Response Types
- API Resources