Pages

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Published by Scroll Versions from this space and version 5.8

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

Table of Contents

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.

    Code Block
    languagebash
    themeRDark
    # 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.

    Code Block
    languagebash
    themeRDark
    # 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.

      Code Block
      languagebash
      themeRDark
      # 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.

      Code Block
      languagebash
      themeRDark
      # 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"]
      }]