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 examplesimulations_list
. Consult the docstrings of these methods for further informationThreediApi 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.
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
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 theretries
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). Theaiohttp_retry
package is shipped withthreedi_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:
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 packageopenapi_client
will disappear in future versions: do not import it anymore. Direct access to the (new) generated API code is possible throughthreedi_api_client.openapi
.The configuration variables are now prefixed with
"THREEDI_API_"
instead of"API_"
.The
"THREEDI_API_HOST"
must not include the version.Advanced users of the asynchronous client (imported from
threedi_api_client.aio
) should start usingthreedi_api_client.ThreediApi
withasynchronous=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()