Skip to content

Migrating from ThreediApiClient to ThreediApi💡

ThreediApiClient is deprecated and will not be supported in the near future. The new way to use the Python API client is via ThreediApi. In order to migrate from the ThreediApiClient to ThreediApi the following changes are needed:

Initialization💡

The following changes are needed to initialize the client.

    # OLD (ThreediApiClient)

    from threedi_api_client import ThreediApiClient

    API_HOST = https://api.3di.live/v3
    API_USERNAME = "black.sheep"
    API_PASSWORD = "myverysecretmehhh"

    config = {
        "API_HOST": API_HOST,
        "API_USERNAME": USERNAME,
        "API_PASSWORD": PASSWORD
    }

    api_client = ThreediApiClient(config=config)

    # NEW (ThreediApi)

    from threedi_api_client.api import ThreediApi
    from threedi_api_client.versions import V3Api

    # CHANGED: provide host without the version (/v3)
    THREEDI_API_HOST = https://api.3di.live 
    THREEDI_API_PERSONAL_API_TOKEN = "your_personal_api_key_here"

    # CHANGED: 
    #  - THREEDI prefix for configuration parameters
    #  - personal api token instead of username & password
    config = {
        "THREEDI_API_HOST": API_HOST,
        "THREEDI_API_PERSONAL_API_TOKEN": THREEDI_API_PERSONAL_API_TOKEN,
    }

    # NOTE: The ": V3Api" typing part is not mandatory, 
    #       but helps your editor with autocomplete
    api_client: V3Api = ThreediApi(config=config)

    # ThreediApi can also be used as context manager
    with ThreediApi() as api_client:
        api_client: V3Api

Usage💡

For example listing and creating a simulation

    # OLD (ThreediApiClient)

    from threedi_api_client import ThreediApiClient
    from openapi_client import SimulationsApi
    from openapi_client.models import Simulation

    # NOTE: Config part ommitted for readability.
    api_client = ThreediApiClient()

    sim_api = SimulationsApi(api_client)

    sim_api.simulations_list()

    organisation_uuid = "<your organisation uuid here>"
    threedimodel_id = 111 # use your own threedimodel id here
    calculation_duration_hrs = 4
    simulation = Simulation(
            name="user guide simulation",
            threedimodel=threedimodel_id,
            organisation=organisation_uuid,
            start_datetime=datetime.utcnow(),
            duration=calculation_duration_hrs * 3600  # in seconds
    )

    sim_api.simulations_create(simulation)

    # NEW (ThreediApi)

    from datetime import datetime
    from threedi_api_client.api import ThreediApi
    from threedi_api_client.versions import V3Api

    # CHANGED: all models should not be imported from threedi_api_client.openapi.models
    from threedi_api_client.openapi.models import Simulation

    # NOTE: Config part ommitted for readability.    
    api_client: V3Api = ThreediApi()

    # CHANGED: V3Api instances contain ALL api call functions previously
    # distributed accross SimulationApi, ThreedimodelApi etc.
    # Thus no extra initialization is needed to perform API calls.
    api_client.simulations_list() 

    # Context manager create simulation example
    with ThreediApi() as api_client:
        organisation_uuid = "<your organisation uuid here>"
        threedimodel_id = 111 # use your own threedimodel id here
        calculation_duration_hrs = 4
        simulation = Simulation(
            name="user guide simulation",
            threedimodel=threedimodel_id,
            organisation=organisation_uuid,
            start_datetime=datetime.utcnow(),
            duration=calculation_duration_hrs * 3600  # in seconds
        )

        api_client.simulations_create(simulation)

Importing 3Di OpenApi models💡

Import 3Di OpenApi models from threedi_api_client.openapi.models instead of openapi_client.models.

    # OLD (ThreediApiClient)

    from openapi_client.models import Simulation

    # NEW (ThreediApi)

    from threedi_api_client.openapi.models import Simulation

API v3-beta💡

If you want to use any of the v3-beta endpoints you need to initialize ThreediApi with and extra version parameter:

    # NEW (ThreediApi)

    from threedi_api_client.api import ThreediApi
    from threedi_api_client.versions import V3BetaApi

    # NOTE: Config part ommitted for readability.    
    #       V3Api now has become V3BetaApi
    api_client: V3BetaApi = ThreediApi(version='v3-beta')

    # V3Beta is a superset of V3Api, so V3Api calls also are supported.
    api_client.simulations_list()

    # V3Beta endpoints can also be used
    api_client.schematisations_list()
    # note: this was the case when writing this docs, this endpoint might now already be part of the (stable) V3Api

Async support💡

The new ThreediApi client also has async support.

    # NEW (ThreediApi)

    from threedi_api_client.api import ThreediApi
    from threedi_api_client.versions import V3BetaApi

    # NOTE: Config part ommitted for readability.    
    api_client: V3BetaApi = ThreediApi(version='v3-beta', asynchronous=True)

    # Now we can await the API functions
    await api_client.simulations_list()