Watson Machine Learning API changes from v3 to v4

API changes from v3 to v4

The v4 version of the Watson Machine Learning REST API and Watson Machine Learning Python client library have some significant differences from the v3 version and from the V4 beta version. The v4 library supports a range of new functionality, including deployment spaces and software specifications.

Refer to this list of changed and deprecated fields and parameters in the Watson Machine Learning API when upgrading an asset from a previous release.

API changes for Watson Machine Learning

These changes support new features and functionality.

For details and examples for the changes listed here, see the documentation for the REST API and the documentation for the Watson Machine Learning Python client library.

General changes

  • The Python package name has changed to ibm_watson_machine_learning.
  • The link for the Python client library documentation has changed from https://wml-api-pyclient-dev-v4.mybluemix.net/ to http://ibm-wml-api-pyclient.mybluemix.net to reflect the general availability of the new library and APIs.
  • All Watson Machine Learning /v4/ APIs will be moved to /ml/v4/.
  • /v4/spaces will be moved to the platform /v2/spaces.
  • The version query parameter is mandatory on every API call.
  • All API methods require an associated space or project.
  • Authorization has changed from being IAM authorization of the Watson Machine Learning instance to membership of the associated space or project.
  • These operations have the return code changed from 200 to 204:
    • /ml/v4/models/{model_id}/content
    • /ml/v4/functions/{function_id}/code
  • The guid field is no longer supported in metadata - use id instead.
  • Runtimes and libraries have been removed and are replaced by environments with software specifications and hardware specifications.
  • The role field is removed from the metadata for all assets.
  • The content of compressed files is no longer inspected by the V4 repository. Instead the file is streamed directly to CAMS. This means that schemas are not read from the function compressed file and must be set explicitly if needed. Automatic decoding of the PMML model in order to autofill some fields for the Watson Machine Learning model will no longer work and these fields need to be explicitly set in the Watson Machine Learning model if needed.
  • The import field will be removed from the model and pipeline payload.
  • Create revision now supports a commit_message.
  • The content_status and content_formats fields have been removed from the model.
  • It is now possible to list all model content using /ml/v4/models/{model_id}/content.
  • Model content can be downloaded by id using /ml/v4/models/{model_id}/content/{attachment_id} and downloaded by search /ml/v4/models/{model_id}/download.
  • Upload and download of function content has changed to the path /ml/v4/functions/{function_id}/code and /ml/v4/functions/{function_id}/code.

Deployment spaces

Creating deployments requires that you have a deployment space, where you can organize all of the assets required for the deployment, including data sources and software specifications. These changes relate to accessing and using spaces.

  • When querying a space, the assets array in the space resource is no longer supported. Instead, use the assets API to get the assets.
  • The resource references project and space in request payloads is no longer supported. Instead, use project_id and space_id string fields.
  • The fields name, description, project_id, space_id and tags are all deprecated. They will exist only in the metadata and not the response body.
  • Tags have not only been moved to the metadata for responses but they are now an array of strings. This applies to the tags that are set in the request payload as well as the tags in the metadata.
  • The space_id is now a mandatory query parameter for all APIs. The only exception is when using POST to create a resource. In this case, space_id is part of the request payload. Note that for Watson Machine Learning resources that can be stored in a project or a space, you must specify either space_id or project_id.
  • The version query parameter can be set on all APIs.
  • The space and project object in the post payload will be replaced by space_id and project_id.
  • The tags field will be an array of string.

Deployment jobs

  • In /v4/deployment_jobs the supported fields are input_data, input_data_reference and output_data_reference. The input_data is meant for inline payload and the output will only be sent to scoring.predictions even though output_data_reference is given, it won’t be persisted in output_data_reference. The output_data_reference is only used when input_data_reference is given. The output_data_reference field will be always used if set.
  • When referencing a Watson Machine Learning resource in a request payload, href is no longer supported. Instead, use id and an optional rev.
  • Using href in jobs_entity_request to reference a deployment is no longer supported. Instead, use id.
  • The parent object in the metadata has been replaced by the parent_id string field in the metadata.

Deep learning models

  • The following fields are deprecated and replaced by model_definition:
    • training_lib in Models resource
    • training_lib in Experiments resource (training_references[].training_lib)
    • training_lib_href in Pipelines resource (document.pipelines[].nodes[].parameters.training_lib_href)
  • All search APIs use the offset query parameter instead of start. Note that the next field can still be used by calling that url directly rather than setting the start parameter and that offset can be used to specify a numerical offset for offset based pagination.
  • You cannot search by custom fields; use tags instead for searching.

  • Use this format to search for custom parameters:

      /v4/....?custom[name]=model&custom[size]=2

Storing an existing model with the new client might require metadata change

A change in functionality for the Python client requires that INPUT_DATA_SCHEMA meta property should be given in a list instead of a dictionary as it now supports multiple input data schemas.

If you stored a model in an earlier version of the Python client, and the model is stored with INPUT_DATA_SCHEMA meta property, when you upgrade and store it again, you must update the meta properties for the model, or the storage operation will fail with this message:

Unexpected type of 'meta_props.inputDataSchema', expected: '<class 'list'>', actual: '<class 'dict'>'.

For example, if your metadata is structured like this:

        "id": "stest",
        "type": "list",
        "fields": [
            {"name": "pregnancies", "type": "integer"},
            {"name": "glucose", "type": "integer"},
            {"name": "diastolic", "type": "integer"},
            {"name": "triceps", "type": "integer"},
            {"name": "insulin", "type": "integer"},
            {"name": "bmi", "type": "float"},
            {"name": "dpf", "type": "float"},
            {"name": "age", "type": "integer"}
        ]
    }

Change the metadata to use an array. For example:

"input_data_schema": [{
"id": "stest",
"type": "list",
"fields": [
{"name": "pregnancies", "type": "integer"},
{"name": "glucose", "type": "integer"},
{"name": "diastolic", "type": "integer"},
{"name": "triceps", "type": "integer"},
{"name": "insulin", "type": "integer"},
{"name": "bmi", "type": "float"},
{"name": "dpf", "type": "float"},
{"name": "age", "type": "integer"}
]
}]

Changes from the V4 Python client beta

Note these changes from the beta version of the V4 Python client to the generally available version.

|Description|Beta python client package usage| New python client package usage| |—|—|—| |Package to install|!pip install watson-machine-learning-client-V4|!pip install ibm-watson-machine-learning| |Import statement|from watson_machine_learning_client import WatsonMachineLearningAPIClient|’from ibm_watson_machine_learning import APIClient| |Client instance creation statement|client = WatsonMachineLearningAPIClient(wml_credentials)|client = APIClient(wml_credentials)| |Package versions|Package version 1.0.99 or higher (Latest version is 1.0.115)|Use version 1.0.9 or higher| |Documentation|https://wml-api-pyclient-dev-v4.mybluemix.net/|http://ibm-wml-api-pyclient.mybluemix.net| |Cloud Object Storage instance reference|cos and cloudobjectstorage for /v4/deployment_jobs|s3 for ml/v4/deployment_jobs For example, use with scoring.input_data_references.type or scoring.output_data_reference.type`|

Accessing the Python client for a “v1” service instance

How you interact with assets developed using a v1 machine learning service instance depends on the type of plan you use.

Accessing the Python client for a “v1” service instance for a Lite user

If you are a Lite plan user, your v1 machine learning service instance is automatically migrated to a v2 service instance and unmigrated assets will be read only. Use these credentials to access v1 assets. Note: to access assets developed with the v1 service instance, you must import and use the V3 or v4-beta APIs.

wml_credentials = {
                      "apikey":"123456789",
                      "url": " https://HIJKL",
"instance_id": "v1 lite instance_id"
}
from ibm_watson_machine_learning import APIClient
wml_client = APIClient(wml_credentials)

Accessing the Python client for a “v1” service instance for a standard/professional user

For standard and professional plan users, during the migration period, you can still access assets trained and deployed using the deprecated v1 service instance and you can create new assets. Use these credentials to access or create v1 assets. Note: to access assets developed with the v1 service instance, you must import and use the V3 or v4-beta APIs.

wml_credentials = {
                      "apikey":"123456789",
                      "url": " https://HIJKL",
"instance_id": "v1 standard instance_id"
}
from ibm_watson_machine_learning import APIClient
wml_client = APIClient(wml_credentials)

Migrating Python functions

After migrating your assets, you must manually update the score() function of Python functions to match the new format. Follow the steps in Migrating Python functions.