Migrating to the Retail API from beta

Recommendations AI now uses the Retail API. This page explains the changes introduced and migration best practices when moving from the v1beta1 version of the Recommendations Engine API (service endpoint https://recommendationengine.googleapis.com) to the generally available Retail API (service endpoint https://retail.googleapis.com).

The Recommendations Engine API and its documentation set remain available, but they will no longer be updated.

This document applies to you only if you started using Recommendations AI when it was in beta.

Best practices

  • Send validate-only traffic before fully migrating.
  • Incremental traffic migration is better than switching all at once. If possible, gradually migrate your traffic from v1beta1 to v2.
  • If you are running services in different regions, it's better to migrate regions one by one to avoid global outage.

Documentation changes

This documentation set is for the generally available Retail API.

The beta documentation set for Recommendations Engine API and its documentation set remain available, but they will no longer be updated. You can find the beta documentation below:

REST and RPC paths

Many changes have been made to the REST and RPC paths. Make sure to review the API documentation for the Retail API to ensure you are calling the Retail API correctly.

All paths now use retail.googleapis.com instead of recommendationengine.googleapis.com.

For example:

v1beta1 Recommendations Engine API:

GET https://recommendationengine.googleapis.com/v1beta1/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/operations/OPERATION_ID

v2 Retail API:

GET https://retail.googleapis.com/v2/PROJECT_NUMBER/locations/global/catalogs/default_catalog/operations/OPERATION_ID

Some resources and methods have been renamed, removed, or newly added. The table below compares v1beta1 and v2 resources and their associated methods side-by-side.

For example, the v1beta1 resource catalogs.catalogItems is equivalent to the v2 resource catalogs.branches.products. The list method, which was available in catalogs.catalogItems for v1beta1, is not available for catalogs.branches.products in v2, so it is indicated as Removed.

Note that links to v1beta1 resources go to the API documentation for v1beta1.

v1beta1 Resource Method v2 Resource Method
catalogs list catalogs list
patch patch
N/A catalogs.branches.operations get
catalogs.catalogItems create catalogs.branches.products create
delete delete
get get
import import
list Removed
patch patch
catalogs.operations get catalogs.operations get
list list
catalogs.eventStores.operations get Removed
catalogs.eventStores.placements predict catalogs.placements predict
catalogs.eventStores.predictionApiKeyRegistrations create Removed
catalogs.eventStores.userEvents collect catalogs.userEvents collect
import import
list Removed
purge purge
rejoin rejoin
write write
N/A operations get

IAM changes

The following changes have been introduced to Retail Identity and Access Management (IAM) roles and permissions:

  • Retail uses IAM roles and permissions in the retail namespace instead of the automlrecommendations namespace that was used by Recommendations Engine v1beta1.
  • The role Admin Viewer has been removed.
  • Permissions for apiKeys have been removed because the predict method no longer requires its own API key.

Catalog and user event schemas

The schemas for catalog and user events have changed in the Retail API.