This document provides guidance on how and why to upgrade to the latest Conversations API domains and version.

Introduction

Upgrading offers many benefits including access to new features, bug fixes, and performance enhancements.

We've put great care into making newer versions backwards compatible. Upgrading most applications to the latest version will not require significant changes.

Upgrading will involve these basic actions:

1. Use the Conversations API universal domains
2. Switch to the latest Conversations API version
3. Modify your application to account for changes resulting from steps #1 & #2

Conversations API universal domains

The following domains will work for all clients and should be used with all Conversations API requests:

Please continue reading to learn how you can take advantage of universal domain benefits even if you are already using the domains themselves.

Benefits of using universal domains

• Backwards compatibility
  Using the new domains will not change the response body.
• Security
  The universal domains support HTTPS automatically and at no extra charge. HTTPS is not available to some older domains due to limitations imposed by our CDN.

      JSONP requests using the universal domains will be validated to mitigate vulnerability to cross site scripting      attacks.

• Rate limit headers
  Responses to requests using the universal domains will include headers that identify your rate limit and current rate, which is useful to avoid being rate limited.
• Authenticity
  The newer domains support the X-Forwarded-For header on submission, which is used to communicate the author IP address to Bazaarvoice when performing submissions from your server to ours. This is essential to increasing the likelihood that your content will be considered authentic.

🚧

Per the Bazaarvoice Authenticity Policy, you must send author IP address attached to each submission. If you fail to send author IP address with your submission, Bazaarvoice may take any action deemed necessary in Bazaarvoice’s sole discretion to protect the integrity of the network. Such actions may include but are not limited to: rejection of your content, halting syndication of your content on the Bazaarvoice network, revocation of your API key, or revocation of your API license.

Latest Conversations API version

Switching to the latest Conversations API version is as simple as changing the value of the apiversion parameter.

/data/reviews.json?apiversion=5.4&passkey=kuy3zj9pr3n7i0wxajrzj04xo

📘

The Conversations API supports functionality beyond the example URL above. Please review the documentation and investigate your application to determine how it integrates with the API.

Benefits of using the latest version

• Backwards compatibility
  Changes will be in the response body, but because they are mostly additive many clients will not need to update their applications unless they want to take advantage of new features. Please see notable differences and changelogs for additional details.
• Security
  Versions prior to 5.4 did not offer secure photo upload.
• New features
  Including internationalization, product statistics, email based authentication, full text search, additional filters & sorts, and lots more. See the changelogs for details.
• Authenticity
  Version 5.4 and greater support the fp parameter, which is used to communicate the end-user device fingerprint to Bazaarvoice. This is important to increasing the likelihood that your content will be considered authentic.

🚧

Per the Bazaarvoice Authenticity Policy, you must send a device fingerprint attached to each submission. If you fail to send a device fingerprint with your submission, Bazaarvoice may take any action deemed necessary in Bazaarvoice’s sole discretion to protect the integrity of the network. Such actions may include but are not limited to: rejection of your content, halting syndication of your content on the Bazaarvoice network, revocation of your API key, or revocation of your API license.

Notable differences

5.4 Conversations PRR & 5.4 Conversations

Conversations PRR is the first version of our platform. It has been superseded by our new Conversations platform, which offers increased performance, feature enhancements and access to our self service Configuration Hub. The newer Conversations Platform supports the most valuable features from Conversations PRR, while eliminating poorly adopted or low value functionality. For clients with access to our Configuration Hub, API keys requested after February 2015 automatically get access to Conversations.

Refer to the 5.4 (Conversations) changelogs to see a list of differences .

XML response type

XML response type is no longer supported in API v5.4 on the Conversations platform. We recommend you move to JSON irrespective of which API version or Conversations platform you are on. If you cannot do that, you may use XML with API v5.4 on the PRR platform, but please plan to switch to JSON in the future.

In addition to the changes mentioned above, responses to requests using .xml are more likely to have changed as compared to their .json counterparts between 4.9 to 5.0.

Further, the responses to .xml requests include an XML schema for that version. The XML schema will necessarily change between versions.

Developers upgrading applications consuming XML responses should pay special attention to the 5.0 changelogs.

Versions 5.0 & 5.1 and "implied locale filtering"

This difference will only impact clients with content from multiple locales not already using the ContentLocale filter.

Versions 5.0 and 5.1 of the API use "implied locale filtering", automatically returning content based on the default locale configured for a client, unless the ContentLocale filter is used to request specific locales. Later versions will return all content irrespective of the default local, unless the ContentLocale filter is used to request specific locales.

To maintain the previous behavior of "implied locale filtering" add filter=ContentLocale:{desired locale here} to your requests.

Product families

Starting with version 5.4, when filtering by product ID all content from that product's "product family" is also returned by default. There is a new excludefamily parameter that you can set to not return product family content.

To maintain the behavior of previous versions add excludefamily=true to your requests.

Version 4.9

Clients using version 4.9 should expect the most differences when migrating to the latest version. Because 4.9 was the first public version, the display and submission responses of later versions include many changes and additions. Clients using 4.9 are more likely to have to update their applications to support the latest display and submission response bodies. See the 5.0 changelogs below for a detailed list.

Sample migration steps

In general, developers can expect to perform steps similar to the following:

📘

No two applications are alike, so the exact steps for migrating to the latest Conversations API version will be different for each application.

1. Analyze the requests your application is making and identify what domain, api version and data from the responses your application is using.
2. Familiarize yourself with the relevant - as determined by your analysis from step #1 - changelogs below.
3. Compare the responses from step #1 with responses to requests using the latest version.
   • Use Bazaarvoice Conversations API Differ for this or,
   • Save the responses and compare them in your diff software of choice.
4. For each difference identified in the previous steps confirm if your app will be impacted.
5. Make any changes in your app based on step #4 and update the requests your app makes to the new universal domains and latest API version.
6. Test in a non-production environment following your organizations best practices/requirements.
7. Deploy your upgraded application to production.