Pages

This guide shows you how to migrate from using an older Recommendations API version to using a newer one.

Migrating from v1 to v2

Changes in v2

  • The API expects a request to include at least one parameter for filtering the recommendation data. This means that you need to define at least one parameter in each of your recommendation configurations.
  • Parameters are now defined inside the params object.
  • You can define multiple values for a given parameter by using an array of strings.
  • You can exclude specific products from the recommendation data by defining the corresponding product IDs in the request.

For more information about the API, see Recommendations API v2.

Updating your code for v2

To migrate from v1 to v2, update your recommendation configurations and requests as follows:

  1. If a recommendation configuration has no parameters, define at least one parameter in the configuration, and update the requests that target the recommendation accordingly.

    # Before ("params" array in a recommendation configuration with v1)
    
    "params": []
    
    # After ("params" array in a recommendation configuration with v2)
    
    "params": [
      "type"
    ]
  2. In requests, enclose parameters inside the params object.

    # Before (parameters in v1 requests)
    
    [{
      "name": "Most viewed products",
      "type": "Books"
    }]
    
    # After (parameters in v2 requests)
    
    [{
      "name": "Most viewed products",
      "params": {
        "type": "Books"
      }
    }]
  3. Optionally, optimize your request code:

    • If you're requesting the same recommendation with the same parameters multiple times, but with different parameter values, combine the separate requests into a single request by defining the parameter values as an array of strings.

      # Before (multiple recommendations)
      
      [{
        "name": "Most viewed products",
        "params": {
          "type": "Books"
        }
      },{
        "name": "Most viewed products",
        "params": {
          "type": "Magazines"
        }
      }]
      
      # After (single recommendation)
      
      [{
        "name": "Most viewed products",
        "params": {
          "type": ["Books", "Magazines"]
        }
      }]
    • If you're requesting a product recommendation and want to exclude specific products from the returned recommendation data, use excludeIds to define the corresponding product IDs.

      # Before (get all products)
      
      [{
        "name": "Most viewed products",
        "params": {
          "type": "Books"
        }
      }]
      
      # After (exclude selected products)
      
      [{
        "name": "Most viewed products",
        "params": {
          "type": "Books"
        },
        "excludeIds": ["123", "456", "789"]
      }]
  • No labels