API Designer & Deployer#

API Designer#

class dataikuapi.dss.apiservice.DSSAPIServiceListItem(client, data)#

An item in a list of API services.

Important

Do not instantiate directly, use dataikuapi.dss.project.DSSProject.list_api_services()

to_api_service()#

Get a handle corresponding to this API service.

Return type:

DSSAPIService

property name#

Get the name of the API service.

Return type:

string

property id#

Get the identifier of the API service.

Return type:

string

property auth_method#

Get the method used to authenticate on the API service.

Usage example:

# list all public API services
for service in project.list_api_services(as_type="list_item"):
    if service.auth_method == 'PUBLIC':
        print("Service {} isn't authenticating requests".format(service.id))
Returns:

an authentication method. Possible values: PUBLIC (no authentication), API_KEYS, OAUTH2

Return type:

string

property endpoints#

Get the endpoints in this API service.

Returns:

a list of endpoints, each one a dict with fields:

  • id : identifier of the endpoint

  • type : type of endpoint. Possible values: STD_PREDICTION, STD_CLUSTERING, STD_FORECAST, STD_CAUSAL_PREDICTION, CUSTOM_PREDICTION, CUSTOM_R_PREDICTION, R_FUNCTION, PY_FUNCTION, DATASETS_LOOKUP, SQL_QUERY

Return type:

list[dict]

class dataikuapi.dss.apiservice.DSSAPIServiceSettings(client, project_key, service_id, settings)#

The settings of an API Service in the API Designer.

Important

Do not instantiate directly, use DSSAPIService.get_settings().

get_raw()#

Get the raw settings of this API Service.

This returns a reference to the raw settings, not a copy, so changes made to the returned object will be reflected when saving.

Returns:

the settings of the API service, as a dict. The definitions of the endpoints are inside the endpoints field, itself a list of dict.

Return type:

dict

property auth_method#

Get the method used to authenticate on the API service

Returns:

an authentication method. Possible values: PUBLIC (no authentication), API_KEYS, OAUTH2

Return type:

string

property endpoints#

Get the list of endpoints of this API service

Returns:

ist of endpoints, each one a dict. Endpoint have different fields depending on their type, but always have at least:

  • id : identifier of the endpoint

  • type : type of endpoint. Possible values: STD_PREDICTION, STD_CLUSTERING, STD_FORECAST, STD_CAUSAL_PREDICTION, CUSTOM_PREDICTION, CUSTOM_R_PREDICTION, R_FUNCTION, PY_FUNCTION, DATASETS_LOOKUP, SQL_QUERY

Return type:

list[dict]

add_prediction_endpoint(endpoint_id, saved_model_id)#

Add a new “visual prediction” endpoint to this API service.

Parameters:
  • endpoint_id (string) – identifier of the new endpoint to create

  • saved_model_id (string) – identifier of the saved model (that is currently deployed to the Flow) to use

add_clustering_endpoint(endpoint_id, saved_model_id)#

Add a new “visual clustering” endpoint to this API service.

Parameters:
  • endpoint_id (string) – identifier of the new endpoint to create

  • saved_model_id (string) – identifier of the saved model (that is currently deployed to the Flow) to use

add_forecasting_endpoint(endpoint_id, saved_model_id)#

Add a new “visual time series forecasting” endpoint to this API service.

Parameters:
  • endpoint_id (string) – identifier of the new endpoint to create

  • saved_model_id (string) – identifier of the saved model (that is currently deployed to the Flow) to use

add_causal_prediction_endpoint(endpoint_id, saved_model_id, compute_propensity=False)#

Add a new “visual causal prediction” endpoint to this API service.

Parameters:
  • endpoint_id (string) – identifier of the new endpoint to create

  • saved_model_id (string) – identifier of the saved model (that is currently deployed to the Flow) to use

  • compute_propensity (bool) – whether propensity should be computed, if True, the model must have a trained propensity model

save()#

Save back these settings to the API Service.

class dataikuapi.dss.apiservice.DSSAPIService(client, project_key, service_id)#

An API Service from the API Designer on the DSS instance.

Important

Do not instantiate directly, use dataikuapi.dss.project.DSSProject.get_api_service()

property id#

Get the API service’s identifier

Return type:

string

get_settings()#

Get the settings of this API Service.

Usage example:

# list all API services using a given model
model_lookup = "my_saved_model_id"
model = project.get_saved_model(model_lookup)
model_name = model.get_settings().get_raw()["name"]
for service in project.list_api_services(as_type='object'):
    settings = service.get_settings()
    endpoints_on_model = [e for e in settings.endpoints if e.get("modelRef", '') == model_lookup]
    if len(endpoints_on_model) > 0:
        print("Service {} uses model {}".format(service.id, model_name))
Returns:

a handle on the settings

Return type:

DSSAPIServiceSettings

list_packages()#

List the versions of this API service.

Returns:

a list of pacakges, each one as a dict. Each dict has fields:

  • id : version (identifier) of the package

  • createdOn : timestamp in milliseconds of when the package was created

Return type:

list[dict]

create_package(package_id)#

Create a new version of this API service.

Parameters:

package_id (string) – version (identifier) of the package to create

delete_package(package_id)#

Delete a version of this API service.

Parameters:

package_id (string) – version (identifier) of the package to delete

download_package_stream(package_id)#

Download an archive of a package as a stream.

The archive can then be deployed in a DSS API Node.

Warning

This call will monopolize the DSSClient until the stream it returns is closed.

Parameters:

package_id (string) – version (identifier) of the package to download

Returns:

the package archive, as a HTTP stream

Return type:

file-like

download_package_to_file(package_id, path)#

Download an archive of a package to a local file.

The archive can then be deployed in a DSS API Node.

Parameters:
  • package_id (string) – version (identifier) of the package to download

  • path (string) – absolute or relative path to a file in which the package is downloaded

publish_package(package_id, published_service_id=None)#

Publish a package on the API Deployer.

Parameters:
  • package_id (string) – version (identifier) of the package to publish

  • published_service_id (string) – identifier of the API service on the API Deployer in which the package will be published. A new published API service will be created if none matches the identifier. If the parameter is not set, the identifier from the current DSSAPIService is used.

API Deployer#

class dataikuapi.dss.apideployer.DSSAPIDeployer(client)#

Handle to interact with the API Deployer.

Do not create this directly, use dataikuapi.dss.DSSClient.get_apideployer()

list_deployments(as_objects=True)#

Lists deployments on the API Deployer

Parameters:

as_objects (boolean) – if True, returns a list of DSSAPIDeployerDeployment, else returns a list of dict. Each dict contains at least a field “id” indicating the identifier of this deployment

Returns:

a list - see as_objects for more information

Return type:

list

get_deployment(deployment_id)#

Returns a handle to interact with a single deployment, as a DSSAPIDeployerDeployment

Parameters:

deployment_id (str) – Identifier of the deployment to get

Return type:

DSSAPIDeployerDeployment

create_deployment(deployment_id, service_id, infra_id, version, endpoint_id=None, ignore_warnings=False)#

Creates a deployment and returns the handle to interact with it. The returned deployment is not yet started and you need to call start_update()

Parameters:
  • deployment_id (str) – Identifier of the deployment to create

  • service_id (str) – Identifier of the API Service to target

  • infra_id (str) – Identifier of the deployment infrastructure to use

  • version (str) – Identifier of the API Service version to deploy

  • endpoint_id (str) – Identifier of the endpoint to deploy if you use a Deploy Anywhere infra. Ignored otherwise

  • ignore_warnings (boolean) – ignore warnings concerning the governance status of the model version(s) to deploy

Return type:

DSSAPIDeployerDeployment

list_stages()#

Lists infrastructure stages of the API Deployer

Return type:

list of dict. Each dict contains a field “id” for the stage identifier and “desc” for its description.

Return type:

list

list_infras(as_objects=True)#

Lists deployment infrastructures on the API Deployer

Parameters:

as_objects (boolean) – if True, returns a list of DSSAPIDeployerInfra, else returns a list of dict. Each dict contains at least a field “id” indicating the identifier of this infra

Returns:

a list - see as_objects for more information

Return type:

list

create_infra(infra_id, stage, type, govern_check_policy='NO_CHECK')#

Creates a new infrastructure on the API Deployer and returns the handle to interact with it.

Parameters:
  • infra_id (str) – Unique Identifier of the infra to create

  • stage (str) – Infrastructure stage. Stages are configurable on each API Deployer

  • type (str) – STATIC, K8S, AZURE_ML, SAGEMAKER, SNOWPARK or VERTEX_AI

  • govern_check_policy (str) – PREVENT, WARN, or NO_CHECK depending if the deployer will check whether the saved model versions deployed on this infrastructure has to be managed and approved in Dataiku Govern

Return type:

DSSAPIDeployerInfra

get_infra(infra_id)#

Returns a handle to interact with a single deployment infra, as a DSSAPIDeployerInfra

Parameters:

infra_id (str) – Identifier of the infra to get

Return type:

DSSAPIDeployerInfra

list_services(as_objects=True)#

Lists API services on the API Deployer

Parameters:

as_objects (boolean) – if True, returns a list of DSSAPIDeployerService, else returns a list of dict. Each dict contains at least a field “id” indicating the identifier of this Service

Returns:

a list - see as_objects for more information

Return type:

list

create_service(service_id)#

Creates a new API Service on the API Deployer and returns the handle to interact with it.

Parameters:

service_id (str) – Identifier of the API Service to create

Return type:

DSSAPIDeployerService

get_service(service_id)#

Returns a handle to interact with a single service, as a DSSAPIDeployerService

Parameters:

service_id (str) – Identifier of the API service to get

Return type:

DSSAPIDeployerService

Infrastructures#

class dataikuapi.dss.apideployer.DSSAPIDeployerInfra(client, infra_id)#

An API Deployer infrastructure.

Do not create this directly, use get_infra()

property id#
get_status()#

Returns status information about this infrastructure

Return type:

dataikuapi.dss.apideployer.DSSAPIDeployerInfraStatus

get_settings()#

Gets the settings of this infra. If you want to modify the settings, you need to call save() on the returned object

Returns:

a dataikuapi.dss.apideployer.DSSAPIDeployerInfraSettings

delete()#

Deletes this infra You may only delete an infra if it has no deployments on it anymore.

class dataikuapi.dss.apideployer.DSSAPIDeployerInfraSettings(client, infra_id, settings)#

The settings of an API Deployer infrastructure

Do not create this directly, use get_settings()

get_type()#

Gets the type of this infra

Returns:

the type of this infra

Return type:

string

add_apinode(url, api_key, graphite_prefix=None)#

Adds an API node to the list of nodes of this infra.

Only applicable to STATIC infrastructures

Parameters:
  • url (str) – url of the API node that will be added to this infra

  • api_key (str) – api key secret to connect to the API node

  • graphite_prefix (str) – graphite prefix for metric reports if graphite is configured

remove_apinode(node_url)#

Removes a node from the list of nodes of this infra. Only applicable to STATIC infrastructures

Parameters:

node_url (str) – URL of the node to remove

get_raw()#

Gets the raw settings of this infra. This returns a reference to the raw settings, not a copy, so changes made to the returned object will be reflected when saving.

Return type:

dict

save()#

Saves back these settings to the infra

class dataikuapi.dss.apideployer.DSSAPIDeployerInfraStatus(client, infra_id, light_status)#

The status of an API Deployer infrastructure.

Do not create this directly, use get_status()

get_deployments()#

Returns the deployments that are deployed on this infrastructure

Returns:

a list of deployments

Return type:

list of dataikuapi.dss.apideployer.DSSAPIDeployerDeployment

get_raw()#

Gets the raw status information. This returns a dictionary with various information about the infrastructure

Return type:

dict

API Services#

class dataikuapi.dss.apideployer.DSSAPIDeployerService(client, service_id)#

An API service on the API Deployer

Do not create this directly, use get_service()

property id#
get_status()#

Returns status information about this service. This is used mostly to get information about which versions are available and which deployments are exposing this service

Return type:

dataikuapi.dss.apideployer.DSSAPIDeployerServiceStatus

import_version(fp)#

Imports a new version for an API service from a file-like object pointing to a version package Zip file

Parameters:

fp (string) – A file-like object pointing to a version package Zip file

get_settings()#

Gets the settings of this service. If you want to modify the settings, you need to call save() on the returned object.

The main things that can be modified in a service settings are permissions

Returns:

a dataikuapi.dss.apideployer.DSSAPIDeployerServiceSettings

delete_version(version)#

Deletes a version from this service

Parameters:

version (string) – The version to delete

delete()#

Deletes this service

You may only delete a service if it has no deployments on it anymore.

class dataikuapi.dss.apideployer.DSSAPIDeployerServiceSettings(client, service_id, settings)#

The settings of an API Deployer Service.

Do not create this directly, use get_settings()

get_raw()#

Gets the raw settings of this deployment. This returns a reference to the raw settings, not a copy, so changes made to the returned object will be reflected when saving.

Return type:

dict

save()#

Saves back these settings to the API service

class dataikuapi.dss.apideployer.DSSAPIDeployerServiceStatus(client, service_id, light_status)#

The status of an API Deployer Service.

Do not create this directly, use get_status()

get_deployments(infra_id=None)#

Returns the deployments that have been created from this published project

Parameters:

infra_id (str) – Identifier of an infra, allows to only keep in the returned list the deployments on this infra. If not set, the list contains all the deployments using this published project, across every infra of the Project Deployer.

Returns:

a list of deployments

Return type:

list of dataikuapi.dss.apideployer.DSSAPIDeployerDeployment

get_versions()#

Returns the versions of this service that have been published on the API Service

Each version is a dict that contains at least a “id” field, which is the version identifier

Returns:

a list of versions, each as a dict containing a “id” field

Return type:

list of dicts

get_raw()#

Gets the raw status information. This returns a dictionary with various information about the service,

Return type:

dict

Deployments#

class dataikuapi.dss.apideployer.DSSAPIDeployerDeployment(client, deployment_id)#

A Deployment on the API Deployer

Do not create this directly, use get_deployment()

property id#
get_status()#

Returns status information about this deployment

Return type:

dataikuapi.dss.apideployer.DSSAPIDeployerDeploymentStatus

get_governance_status(version='')#

Returns the governance status about this deployment if applicable It covers all the embedded model versions

Parameters:

version (str) – (Optional) The specific package version of the published service to get status from. If empty, consider all the versions used in the deployment generation mapping.

Return type:

dict InforMessages containing the governance status

get_settings()#

Gets the settings of this deployment. If you want to modify the settings, you need to call save() on the returned object

Returns:

a dataikuapi.dss.apideployer.DSSAPIDeployerDeploymentSettings

start_update()#

Starts an asynchronous update of this deployment to try to match the actual state to the current settings

Returns:

a dataikuapi.dss.future.DSSFuture tracking the progress of the update. Call wait_for_result() on the returned object to wait for completion (or failure)

delete(disable_first=False, ignore_pre_delete_errors=False)#

Deletes this deployment. The disable_first flag automatically disables the deployment before its deletion.

Parameters:
  • disable_first (boolean) – If True, automatically disables this deployment before deleting it. If False, will raise an Exception if this deployment is enabled.

  • ignore_pre_delete_errors (boolean) – If True, any error occurred during the actions performed previously to delete the deployment will be ignored and the delete action will be performed anyway.

get_open_api()#

Gets the OpenAPI document of this deployment if it’s available or raise a 404 error.

Returns:

a dataikuapi.dss.apideployer.DSSAPIDeployerDeploymentOpenApi

run_test_queries(endpoint_id=None, test_queries=None)#

Runs test queries on a deployment and returns results as a dict

Parameters:
  • endpoint_id (str) – Mandatory if the deployment has multiple endpoints

  • test_queries (list) – Queries as str, formatted as [{“q”: {“features”: {“feat_1”: “value”, …}}, {…}, … ]. If left to None, the test queries of the current version of the service will be used.

Return type:

dict

Usage example

import dataiku

client = dataiku.api_client()
deployer = client.get_apideployer()
deployment = deployer.get_deployment('service14');

test_queries = [{'q': {'features': {
    'Pclass': '200',
    'Sex': 'male',
    'Age': '22',
    'Embarked': 'S'
}}}]

# run existing test queries on deployement endpoint (if unique, else error)
test_queries_result = deployment.run_test_queries()

# run specified test queries on deployement "survived" endpoint
test_queries_result = deployment.run_test_queries(endpoint_id="survived", test_queries=test_queries)

# run existing test queries on deployement  "survived" endpoint
test_queries_result = deployment.run_test_queries(endpoint_id="survived")

# run specified test queries on deployement endpoint (if unique, else error)
test_queries_result = deployment.run_test_queries(test_queries=test_queries)
class dataikuapi.dss.apideployer.DSSAPIDeployerDeploymentSettings(client, deployment_id, settings)#

The settings of an API Deployer deployment.

Do not create this directly, use get_settings()

get_raw()#

Gets the raw settings of this deployment. This returns a reference to the raw settings, not a copy, so changes made to the returned object will be reflected when saving.

Return type:

dict

set_enabled(enabled)#

Enables or disables this deployment

Parameters:

enabled (bool) – True/False to Enable/Disable this deployment

set_single_version(version)#

Sets this deployment to target a single version of the API service

Parameters:

version (str) – Identifier of the version to set

save(ignore_warnings=False)#

Saves back these settings to the deployment

Parameters:

ignore_warnings (boolean) – ignore warnings concerning the governance status of the model version(s) to deploy

class dataikuapi.dss.apideployer.DSSAPIDeployerDeploymentStatus(client, deployment_id, light_status, heavy_status)#

The status of an API Deployer deployment.

Do not create this directly, use get_status()

get_light()#

Gets the ‘light’ (summary) status. This returns a dictionary with various information about the deployment, but not the actual health of the deployment

Return type:

dict

get_heavy()#

Gets the ‘heavy’ (full) status. This returns a dictionary with various information about the deployment

Return type:

dict

get_service_urls()#

Returns service-level URLs for this deployment (ie without the enpdoint-specific suffix)

Returns:

a list of service-level URLs for this deployment

Return type:

list

get_health()#

Returns the health of this deployment as a string

Returns:

HEALTHY if the deployment is working properly, various other status otherwise

Return type:

string

get_health_messages()#

Returns messages about the health of this deployment