IBM Cloud Docs
API version comparison

API version comparison

For most API methods, the request parameters and response bodies differ between v1 and v2. Learn about the equivalent or alternative v2 methods that you can use to do actions that are supported by the v1 API.

The comparison information assumes you are using the latest version of the v1 API (version 2019-04-30) and compares it to the latest version of the v2 API (version 2020-08-30).

Environments

There is no concept of an environment in v2. The deployment details such as size and index capacity are managed based on the service plan type. In v2, collections are organized in projects. You can create different types of projects to apply default configuration settings to the collections that you add to the projects.

There are no equivalent methods in v2 for the v1 environment methods. However, the following table shows v2 methods that serve similar functions to the corresponding v1 methods. The supported parameters and response bodies that are returned for each method differ also.

Environment API action support details
Action v1 API Related v2 API
Create an environment POST /v1/environments POST /v2/projects
List environments GET /v1/environments GET /v2/projects
Get environment info GET /v1/environments/{environment_id} GET /v2/projects/{project_id}
Update an environment PUT /v1/environments/{environment_id} POST /v2/projects/{project_id}
v2 uses POST instead of PUT.
Delete an environment DELETE /v1/environment/{environment_id} DELETE /v2/projects/{project_id}
List fields across collections GET /v1/environments/{environment_id}/fields GET /v2/projects/{project_id}/fields

Configurations

The v2 API does not have an endpoint that is dedicated to configurations. Instead, configuration settings for projects, collections, and queries are specified directly in the API for those objects. Not all of the configuration parameters that are available in v1 are available or applicable in v2.

In the v1 configuration API, the JSON object that is used to specify a configuration object contains several parameters that are either available in different formats from other v2 endpoints or are not available in v2. The following table describes how to find related parameters in v2.

You cannot customize the conversion of documents during the ingestion process in v2 as you can in v1.

Configuration setting details
v1 configuration parameter v2 API
"conversions.html": { ... } Not available
"conversions.image_text_recognition": { ... } Not available from the API. However, you can enable optical character recognition (OCR) for a collection from the product user interface to extract text from images. OCR has other benefits, too. For example, if a page in a document can't be processed, OCR converts the page into an image and scans it to ensure that the document is uploaded successfully.
"conversions.json_normalizations": { ... } Moved to the Collections API.
"conversions.pdf": { ... } Not available. If you used special parameters to extract text from images in PDFs, enable optical character recognition (OCR) from the product user interface for the collection that contains the PDFs instead.
"conversions.segment": { ... } Not available programmatically. You can split a document at each occurrence of an SDU-generated field such as subtitle from the product user interface.
The segment_metadata object with parent_id, id, and total_segments information is not available in v2. You can use the metadata.parent_document_id field to find the common parent for many document segments.
"conversions.word": { ... } Not available
"enrichments": { ... }

/v2/projects/{project_id}/enrichments, /v2/projects/{project_id}/collections/{collection_id}
Use the enrichments API to explore existing enrichments. Use the collections API to see and change the enrichments that are enabled on a field in a collection.
Some enrichments are applied to the service by default based on the type of project that you create. For more details, see Default project settings.
The version of the Entities enrichment that is available in v2 doesn't include the disambiguation field, which in v1 contains the disambiguation information for the entity and includes the entity subtype information.
The following enrichments are not available in v2:

  • Categories
  • Concepts
  • Emotion
  • Relations
  • Semantic roles
  • Sentiment of Entities
  • Sentiment of Keywords
"normalizations": [ ... ] Moved to the Collections API.
"source": { ... } Not available. Configure connections to external data sources through the user interface. For more information, see Creating collections.

Collections

Collections API support details
Action v1 API v2 API
Create a collection POST /v1/environments/{environment_id}/collections POST /v2/projects/{project_id}/collections
The supported parameters and responses differ between the two versions. See the collection notes.
List collections GET /v1/environments/{environment_id}/collections GET /v2/projects/{project_id}/collections
In v2, only the collection ID and name of each collection are returned in the list. You must use the Get collection method to return more details about each collection.
Get collection details GET /v1/environments/{environment_id}/collections/{collection_id} GET /v2/projects/{project_id}/collections/{collection_id}
See the collection notes.
Update a collection PUT /v1/environments/{environment_id}/collections/{collection_id} POST /v2/projects/{project_id}/collections/{collection_id}
Delete a collection DELETE /v1/environments/{environment_id}/collections/{collection_id} DELETE /v2/projects/{project_id}/collections/{collection_id}
In v2, the status field is not returned in the response.
List collection fields GET /v1/environments/{environment_id}/collections/{collection_id}/fields
v1 lists the fields per collection.
GET /v2/projects/{project_id}/fields
v2 lists fields per project instead. You can pass a single collection ID with the collection_ids parameter to get fields from a single collection.

Collections API notes

The following table shows the important differences between the v1 and v2 collection APIs.

Collections API notes
Method Notes
Create a collection The v2 response doesn't include the status and configuration_id fields. You can get status information for a specific document by using the Get document details method.
The objects disk_usage, training_status, and crawl_status are not present in the response body in v2. The document_counts object is not present in the response body in v2 currently. Training status is returned in the Get project method response. The other information is not available in v2. In v2, you can define the enrichments to apply to the documents in the collection by specifying an optional enrichments object.
Get collection details The v2 response doesn't include the status and configuration_id fields. You can get status information for a specific document by using the Get document details method.
The objects document_counts, disk_usage, training_status, and crawl_status are not present in the response body in v2. Training status is returned in the Get project method response. The other information is not available in v2. For example, you cannot get the document count for a collection and cannot get the crawl status for a collection that connects to an external data source in v2. In v2, you can get information about the enrichments that are applied to the collection.
Update a collection v2 uses POST instead of PUT. In v2, you can update the enrichments that are applied to the documents in the collection by specifying an optional enrichments object.
The v2 response doesn't include the status and configuration_id fields.

Query modifications

The method that was available in v1 for configuring tokenization programmatically is not supported in the v2 API.

Query modifications API support details
v1 API v2 API
Tokenization dictionary API Not available.
Expansions v1 API Expansions v2 API
Stopwords v1 API Stopwords v2 API

Documents

Documents API support details
Action v1 API v2 API
List documents Not available from the v1 API GET /v2/projects/{project_id}/collections/{collection_id}/documents
Create a document POST /v1/environments/{environment_id}/collections/{collection_id}/documents POST /v2/projects/{project_id}/collections/{collection_id}/documents
Unlike v1, the v2 response does not include a notices object. However, you can get notices information by using the Get document details method in v2.
Update a document POST /v1/environments/{environment_id}/collections /{collection_id}/documents/{document_id} POST /v2/projects/{project_id}/collections/{collection_id}/documents/{document_id}
When you update a document that was split, all of the document segments are overwritten.
Get document details GET /v1/environments/{environment_id}/collections /{collection_id}/documents/{document_id} GET /v2/projects/{project_id}/collections/{collection_id}/documents/{document_id}
In v2, there is no statusDescription. v2 has a children object with information about any notices that are associated with the child documents that are generated during ingestion.
Delete a document DELETE /v1/environments/{environment_id}/collections /{collection_id}/documents/{document_id} DELETE /v2/projects/{project_id}/collections/{collection_id}/documents/{document_id}
Segments of an uploaded document cannot be deleted individually. Delete all segments with a DELETE request that includes the parent_document_id of a segment result.

v2 introduces a custom header that is named X-Watson-Discovery-Force that is not available in v1. You must include the header when you perform an operation on data that is shared across many collections to indicate that you want to perform the operation in each collection. If you do not include the header, a 403 error is returned.

Fields from JSON files that are added to a collection are converted differently during ingestion between v1 and v2. For more information about how JSON files are stored in the v2 index, see JSON files.

Queries

Documents API support details
Action v1 API v2 API
Query a collection Supports a GET or POST request.
GET or POST /v1/environments/{environment_id}/collections/{collection_id}/query
Queries a project. To specify a single collection, include the {collection_id} parameter. Supports a POST request only.
POST /v2/projects/{project_id}/query
Query multiple collections GET or POST /v1/environments/{environment_id}/query POST /v2/projects/{project_id}/query
Query system notices GET /v1/environments/{environment_id}/collections/{collection_id}/notices GET /v2/projects/{project_id}/collections/{collection_id}/notices
Query multiple collection system notices GET /v1/environments/{environment_id}/notices GET /v2/projects/{project_id}/notices
Get Autocomplete suggestions /v1/environments/{environment_id}/collections/{collection_id}/autocompletion GET /v2/projects/{project_id}/autocompletion
See the query notes.

Some query result configurations are applied to the service by default based on the type of project that you create. For more details, see Default project settings.

Query notes

  • v2 queries return results from all of the collections in the project. To restrict the query to use only certain collections within the project, use the collection_ids query parameter. You cannot query multiple collections that are added to different projects with one v2 query request.

  • v2 results include a confidence field, but not a score field.

    The confidence score replaced the score information in v1, but score was retained for backward compatibility. In v2, only the confidence field is returned.

  • Use POST calls (instead of GET calls) to submit queries with v2.

  • v1 queries accept many parameters. The Query parameters comparison table maps v1 parameters to v2 parameters.

    Query parameters comparison
    v1 parameter v2 parameter Notes
    N/A collection_ids Use this parameter in v2 to specify collection ids.
    filter filter Same expression language.
    query query Same expression language.
    natural_language_query natural_language_query No notes.
    passages passages The passage format changed and was enhanced in v2. The passages:true parameter changed to passages.enable:true. In addition to the count, characters, and fields options, you can specify per_document, which ranks the documents by document quality, and then returns the highest-ranked passages per document. You can also specify find_answers to return an answer object per passage, which contains a succinct answer to the query.
    aggregation aggregation Same expression language.
    count count No notes.
    offset offset No notes.
    return return No notes.
    sort sort No notes.
    highlight highlight If passages.enabled and passages.per_document are true, then passages are returned for each document instead of highlights.
    spelling_suggestions spelling_suggestions No notes.
    deduplicate N/A Not supported in v2.
    similar similar The format changed in v2. The similar:true parameter changed to similar.enable:true. The document_ids and fields parameters changed from strings to string arrays. The document_ids parameter now is required if enabled is true.
    bias N/A Not supported in v2.

Training data

You can use the v1 training data API to work with two related objects:

  • trained queries
  • examples that are used to train the queries

These two objects have separate API endpoints in v1. In v2, the examples that are used to train each query are provided together with the query and only one endpoint is used to work with the training data.

For example, to add a trained query and its training example documents in v2, you use the request POST /v2/projects/{project_id}/training_data/queries and pass the query and all examples in the payload of one call. Similarly, if you want to update one example in the training set in v2, you must pass the query and the modified example (along with all of the other examples) to the v2 update endpoint. In v1, to update the example information, you use the update example endpoint to modify one example only.

Another important difference between v1 and v2 is that in v1, the trained model is associated with a particular collection. In v2, the trained model is associated with a project. You can use the data from multiple collections within a project to train a relevancy model. When you create or update training examples in v2, the API requires the collection_id for the collection where the document is stored.

Training data API support details
Action v1 API v2 API
List training data GET /v1/environments/{environment_id}/collections/{collection_id}/training_data GET /v2/projects/{project_id}/training_data /queries
Add query to training data POST /v1/environments/{environment_id}/collections/{collection_id}/training_data POST /v2/projects/{project_id}/training_data /queries
Delete all training data DELETE /v1/environments/{environment_id}/collections/{collection_id}/training_data DELETE /v2/projects/{project_id}/training_data /queries
Get details about a query GET /v1/environments/{environment_id}/collections/{collection_id}/training_data/{query_id} GET /v2/projects/{project_id}/training_data /queries/{query_id}
Delete a training data query DELETE /v1/environments/{environment_id}/collections/{collection_id}/training_data/{query_id} DELETE /v2/projects/{project_id}/training_data /queries/{query_id}
List examples for a training data query GET /v1/environments/{environment_id}/collections/{collection_id}/training_data/{query_id}/examples GET /v2/projects/{project_id}/training_data /queries/{query_id}
The examples are in the list that is returned with the query.
Add example to training data query POST /v1/environments/{environment_id}/collections/{collection_id}/training_data/{query_id}/examples POST /v2/projects/{project_id}/training_data /queries/{query_id}
Use the Create training query method in v2 and pass all examples when you create the query. Otherwise, use the update API.
Delete example for training data query DELETE /v1/environments/{environment_id}/collections/{collection_id}/training_data/{query_id}/examples/{example_id} POST /v2/projects/{project_id}/training_data/ queries/{query_id}
Use the v2 training_data update method.
Change label or cross-reference for example PUT /v1/environments/{environment_id}/collections/{collection_id}/training_data/{query_id}/examples/{example_id} POST /v2/projects/{project_id}/training_data/ queries/{query_id}
Use the v2 training_data update method.
Get details for a training data example GET /v1/environments/{environment_id}/collections/{collection_id}/training_data/{query_id}/examples/{example_id} Not available. Use the Read all examples call to get all examples associated with a query and find the example that you need in the returned list.

User data

The user data API is the same in v2 and v1.

User data API support details
Action v1 API v2 API
Delete DELETE /v1/user_data DELETE /v2/user_data
Similar to v1. Use customer_id to delete the data associated with that customer ID.

Events and feedback

The v1 events and feedback API (/v1/events) is not available in v2.

Credentials

The v1 credentials API (/v1/environments/{environment_id}/credentials) is not available in v2. The function is available from the v2 product user interface.

Gateway configuration

The v1 gateways API (/v1/environments/{environment_id}/gateways) is not available in v2. The function is available from the v2 product user interface. For more information, see Installing IBM Secure Gateway for on-premises data.

Status codes

For almost every API method, the status codes that are returned for v2 requests are different from the status codes that are returned for v1 requests.