Usage

The threedi_api_client.ThreediApi is the main entry point to make calls to the 3Di API. It handles the login process for you and can be directly used as client for all API endpoints.

In earlier versions of this library the main entry point was threedi_api_client.ThreediApiClient. This method will remain available until threedi_api_client version 4.0. Read below how to migrate from ThreediApiClient to ThreediApi.

class threedi_api_client.ThreediApi(env_file=None, config=None, version='v3', asynchronous=False, retries=3)

Client for the 3Di API.

The API object exposes numerous methods that interface with the API, all named according to the pattern {resource}_{action}, for example simulations_list. Consult the docstrings of these methods for further information

ThreediApi requires a THREEDI_API_HOST and user credentials. These can either be stored in a .env file, supplied via environment variables, or passed as a config dictionary.

The preferred way of setting user credentials is using a “Personal API Key” in the variable ‘THREEDI_API_PERSONAL_API_TOKEN’. Using ‘THREEDI_API_USERNAME’ and ‘THREEDI_API_PASSWORD’ to authenticate is also supported, but considered legacy. Consider upgrading to personal API keys if you are using this form of authentication.

  1. A sample .env file could look like this:

    THREEDI_API_HOST=https://api.3di.live
THREEDI_API_PERSONAL_API_TOKEN=lHtKAuCV.secret123

This is used in your script as follows:

from threedi_api_client import ThreediApi

env_file = "<path>/.env"
with ThreediApi(env_file=env_file) as api:
    ...

2) The same variables can be set as environment variables from the terminal that you use to run the python interpreter with. On Windows:

set THREEDI_API_HOST "https://api.3di.live"
set THREEDI_API_PERSONAL_API_TOKEN "lHtKAuCV.secret123"

On Linux or OSX:

export THREEDI_API_HOST=https://api.3di.live
export THREEDI_API_PERSONAL_API_TOKEN=lHtKAuCV.secret123

  1. The config keyword argument can be used like:

from threedi_api_client import ThreediApi
from getpass import getpass

config = {
    "THREEDI_API_HOST": "https://api.3di.live",
    "THREEDI_API_PERSONAL_API_TOKEN": getpass(),
}

with ThreediApi(config=config) as api:
    ...
Parameters:

  • env_file (str or pathlib.Path) – path to a configuration file

  • config (dict) – configuration dictionary for this client

  • version (str) – the API version to use (default: ‘v3’)

  • asynchronous (bool) – whether to return an asynchronous API client for usage with asyncio. Note: this requires installation of threedi_api_client[aio].

  • retries (int or object) – the number of retries; see notes section for more granular control over the retry policy

Returns:

This class constructs an Api object that was autogenerated by the OpenAPI generator. The autogenerated code lives under threedi_api_client.openapi.

Notes

OAuth2 For using OAuth2, supply an THREEDI_API_ACCESS_TOKEN. If the THREEDI_API_ACCESS_TOKEN has expired, there are 3 methods implemented for automatic token renewal:

  • refresh token without client secret: supply a THREEDI_API_REFRESH_TOKEN

  • refresh token with client secret: supply a THREEDI_API_REFRESH_TOKEN and THREEDI_API_CLIENT_SECRET

  • client credentials flow: supply a THREEDI_API_CLIENT_SECRET

Timeouts

A request without a timeout may block your python script indefinitely. It is always a good idea to prevent this by setting a timeout. Do this using the _request_timeout parameter on every api request. It is currently not possible to configure a default timeout.

Retry policy

It is common to configure a retry policy to prevent exceptions due to the service being temporarily unavailable. The ThreediApi supports this through the retries parameter. Due to different backends, the configuration details differ between synchronous and asynchronous usage.

For basic usage, supply an integer (which is the maximum number of retries):

>>> api = ThreediApi(..., retries=3)

For synchronous usage, you may also supply a urllib3.util.Retry object (see urllib3 docs):

>>> import urllib3
>>> policy = urllib3.util.Retry(total=3, backoff_factor=1.0)
>>> api = ThreediApi(..., retries=policy)

For asynchronous usage, you may also supply a aiohttp_retry.ExponentialRetry object. See the aiohttp_retry docs). The aiohttp_retry package is shipped with threedi_api_client.

>>> from threedi_api_client.aio import aiohttp_retry
>>> policy = aiohttp_retry.ExponentialRetry(attempts=3, factor=1.0)
>>> api = ThreediApi(..., retries=policy)

Other configuration options are:

- the exceptions on which to retry (default: None)
- the statuses on which to retry (default: 413, 429, 503, 504)
- the HTTP methods on which to retry (default: 'DELETE', 'GET', 'HEAD', 'OPTIONS', 'PUT', 'TRACE')

Migration from ThreediApiClient

Formerly, the threedi_api_client.ThreediApiClient was used to interact with the 3Di API. As of threedi_api_client version 4, this method is deprecated. Currently, both methods are allowed, but the legacy one will give warnings.

There are three changes:

  1. The ThreediApi object directly exposes methods to interact with 3Di API resources. There is no need of separately constructing api objects for each resource. The root package openapi_client will disappear in future versions: do not import it anymore. Direct access to the (new) generated API code is possible through threedi_api_client.openapi.

  2. The configuration variables are now prefixed with "THREEDI_API_" instead of "API_".

  3. The "THREEDI_API_HOST" must not include the version.

  4. Advanced users of the asynchronous client (imported from threedi_api_client.aio) should start using threedi_api_client.ThreediApi with asynchronous=True.

Take for example a script that looks like this:

from threedi_api_client import ThreediApiClient
from openapi_client import SimulationsApi

config = {
    "API_HOST": "https://api.3di.live/v3.0"
    "API_USERNAME": "your.username"
    "API_PASSWORD": "your.password"
}

with ThreediApiClient(config=config) as api_client:
    api = SimulationsApi(api_client)
    result = api.simulations_list()

Applying the changes listed above, it is refactored to this:

from threedi_api_client import ThreediApi

config = {
    "THREEDI_API_HOST": "https://api.3di.live",  # no version!
    "THREEDI_API_PERSONAL_API_TOKEN": "your_personal_api_token_here"
}

with ThreediApi(config=config) as api:
    result = api.simulations_list()