September 1, 2015 | API upgrade overview

Introduction

On April 9, 2015 Bazaarvoice announced two important changes to our Conversations API services:

  • End of service for Conversations API versions older than 5.2 (4.9, 5.0, 5.1)
  • End of service for Conversations API requests using custom domains

Both of these changes will go into effect at midnight NACDT on April 30, 2016.

Before this date, all developers should verify that all of their Conversations API calls:

  1. Use a current version of the API (5.2, 5.3, 5.4 – 5.4 is recommended)
  2. Use the universal domain (“api.bazaarvoice.com” or “stg.api.bazaarvoice.com”)

Our newer APIs and universal domain system offer developers important feature and performance advantages. To best serve our customers, Bazaarvoice is focusing its API efforts on the latest, highest performing API services. By deprecating older versions, we can refocus our energies on the current and future API services, which we believe offer the most benefits to our customers.

In summary, on April 30, 2016, calls to Conversations API versions released before 5.2 (versions 4.9, 5.0, and 5.1) will no longer function. In addition, all Conversations API calls, regardless of version, made to a custom domain (such as “ReviewStarsInc.ugc.bazaarvoice.com” or “c7.ugc.bazaarvoice.com”) will no longer respond. If either of these configurations apply to your website or application, you will receive an interruption in service. To avoid service disruption, you must upgrade to the current Conversations API (5.4) and use the universal domain (“api.bazaarvoice.com” or “stg.api.bazaarvoice.com”).

Assistance

Bazaarvoice is committed to making this transition easy for developers. We are prepared to assist our API customers in a number of ways:

  • Documentation – We have specific documentation to help.
  • Support – Our support team is ready to address any questions you may have.
  • Services – Our services teams are available to provide additional assistance.

If you have any questions about this notice, please submit a case in Spark. We will periodically update our developer blog and our developer Twitter feed (@BazaarvoiceDev) as we move closer to the change of service date.

Using the universal domain

API requests should be updated to use the universal domain. The following domains will work for all clients and should be used with all Conversations API requests:

Environment Domain Description
Staging stg.api.bazaarvoice.com Used while developing your application.
Production api.bazaarvoice.com Used when your application is complete.

API requests should NOT include a custom domain. For example, the following API call is incorrect and will no longer function after April 30, 2016:

http://ReviewStarsInc.ugc.bazaarvoice.com/data/reviews.json?apiversion=5.4&passkey=kuy3zINVALIDKEYajrzj04xo&Filter=ProductId:1000001&Filter=HasComments:true&Sort=Rating:desc&Limit=10

This request will also cease to function:

http://c7.ugc.bazaarvoice.com/data/reviews.json?apiversion=5.4&passkey=kuy3zINVALIDKEYajrzj04xo&Filter=ProductId:1000001&Filter=HasComments:true&Sort=Rating:desc&Limit=10

All API requests should be routed through the universal domains. The following example is correct:

http://api.bazaarvoice.com/data/reviews.json?apiversion=5.4&passkey=kuy3zINVALIDKEYajrzj04xo&Filter=ProductId:1000001&Filter=HasComments:true&Sort=Rating:desc&Limit=10

Benefits of the universal domain

The universal domain offers these benefits:

  • 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.
  • 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 end-user IP address to Bazaarvoice. This is an essential element in the rating of content for authenticity.

Upgrading to the latest API version

You can easily identify the version of your API requests by looking at the URL. The “apiversion” parameter in the query string identifies the version. The following example illustrates an API request using an “end of life” API version:

http://api.bazaarvoice.com/data/reviews.json?apiversion=5.1&passkey=kuy3zINVALIDKEYajrzj04xo&Filter=ProductId:1000001

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

http://api.bazaarvoice.com/data/reviews.json?apiversion=5.4&passkey=kuy3zINVALID KEYajrzj04xo&Filter=ProductId:1000001

Benefits of using the latest API version

  • Backwards compatibility
    • Most changes occur in the response body.
    • Many are additive.
    • Many clients will not need to update their applications unless they want to take advantage of new features.

Please see notable differences (below) and changelogs for additional details.

  • New features
    • Internationalization
    • Product statistics
    • Email-based authentication
    • Full text search
    • New filters
    • Additional sorts

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.

  • Security

Versions prior to 5.4 do not offer secure photo upload.

Notable differences and highlights

XML responses

Calls requesting the XML format are likely to have more significant changes in newer versions of the API. You can identify XML requests by reviewing your request URL. The XML option is highlighted in the following request:

http://api.bazaarvoice.com/data/reviews.xml?apiversion=5.4&passkey=kuy3zINVALIDKEYajrzj04xo&Filter=ProductId:1000001

Compared to a contrasting request using JSON:

http://api.bazaarvoice.com/data/reviews.json?apiversion=5.4&passkey=kuy3zINVALIDKEYajrzj04xo&Filter=ProductId:1000001

5.0 responses to requests using XML are more likely to have changed as compared to their JSON counterparts. You should carefully review the XML schema and compare your current API version to the schema for the upgrade version (5.4). If you are using XML with version 4.9 you should pay particular attention to the schema changes and review the 5.0 changelog as well as the changelog for the upgrade version (5.4 is recommended).

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 remove product family content from your requests.  To maintain the behavior of previous versions add “excludefamily=true” to the application’s requests.

Special considerations for version 4.9 users

As the oldest version currently available, users of version 4.9 should expect the most differences when migrating. Display and submission responses of later versions include many changes and additions. Developers using version 4.9 are more likely to have to update their applications to support the latest display and submission response bodies. In particular, you should review the changes in version 5.0 as well as the changes listed in the upgrade version (5.4 is recommended). See the 5.0 changelog in Developer Portal’s Upgrade Guide for a detailed list.

Versions 5.0, 5.1 and implied locale filtering

This difference will impact only those 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. API versions 5.2 and later will return all content irrespective of the default local, unless the ContentLocale filter is used to request specific locales.

To maintain the behavior of API versions 5.0 and 5.1 (“implied locale filtering”), add filter=ContentLocale:{insert desired locale here} to your requests.

Additional resources

In addition to the items listed in the Assistance section above, the following resources are available in the Bazaarvoice Developer Portal: