API changes (Watson Machine Learning)

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.

Managing API changes using a version date

Watson Machine Learning REST API now includes a VersionDate parameter that you can use to associate your model, script, or function code with a particular version of the API. This can help you avoid needing to update your code if a new feature is introduced in a later version. For details, see the REST API documentation.

API changes from Cloud Pak for Data versions 3.0 to 3.5

These changes might require that you modify your code to execute successfully on the new release.

See Using Watson Machine Learning in a notebook for links to sample notebooks that demonstrate this new functionality.

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

All features that were deprecated features in Cloud Pak for Data 3.0 have been removed.
The guid will no longer be supported in metadata; use id instead.
The legacy concepts runtimes and libraries have been removed and are replaced by environments.
It is no longer possible to search by custom fields, use tags instead for searching.
All search APIs use the offset query parameter instead of start (start may be silently supported for backward compatibility). 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.
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 WML 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. For models, use content_location to import the model from training output.
Create revision now supports a commit_message.
The space and project object in the POST payload will be replaced by space_id and project_id.
The tags field supports an array of string.
The content_status and content_formats field will be removed from the model. Use content_import_state field
You can now list all model content using /ml/v4/models/{model_id}/content.
You can now download model content by id: /ml/v4/models/{model_id}/content/{attachment_id} and download 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`.

Support for new features in V4 API

The following APIs support new features in Watson Machine Learning:

Model definitions
Training definitions
Instances
Remote Training Systems

For details, see Watson Machine Learning REST API.

Removal of fields that were deprecated in IBM Cloud Pak for Data 3.0.1

The following fields were deprecated in IBM Cloud Pak for Data 3.0.1. Support has now been discontinued.

Field name or technique	Usage	Replace with
`href`	referencing a Watson Machine Learning resource in a request payload	`id`
`assets` array	querying a space	assets API
`project` and `space` resoure references	request payloads	`project_id` and `space_id` string fields
`name`, `description`, `space_id`, `tags`	response body	moved to metadata tags are now an array of strings
`parent`	metadata	`parent_id` string field
`training_lib`	in Models resource	`model_definition`
`training_lib`	in Experiments resource (`training_references[].training_lib`)	`model_definition`
`training_lib_href`	in Pipelines resource (`document.pipelines[].nodes[].parameters.training_lib_href`)	`model_definition`
`href`	reference a deployment in `jobs_entity_request`	`id`
Get all spaces using `/v4/spaces`	load all assets for each space	use specific APIs for getting assets

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