The Conversations API lets you programmatically retrieve and submit Bazaarvoice Conversations data for use in your applications. To learn more, go to the Conversations API documentation home page.

Contents

(+ show- hide)

This documentation identifies Conversations API features that should be avoided because we intend to deprecate them in the future.

Introduction

We're thinking about the future of the Conversations API and we want you to be prepared. Your applications will be easier to upgrade to future API releases if you avoid the features below.

The following section describes features that will either not be available in future releases of the Conversations API or its successors or continue to be available, but with different functionality and/or altered behavior.

Not available in future releases

XML content-type

Using .xml is prohibited by our Conversations API Terms of Use - 4.(d)(iii) and has been disabled for API keys issued after August 29th, 2016.

Future releases of the Conversations API will not support returning responses formatted as XML. Instead you should use JSON or JSONP. The following examples demonstrate future compatible and incompatible requests:

Incompatible

GET https://stg.api.bazaarvoice.com/data/reviews.xml?apiversion=[LATEST_VERSION]&passkey=[API_KEY]&Filter=ProductId:[PRODUCT_ID]

Compatible

JSON

GET https://stg.api.bazaarvoice.com/data/reviews.json?apiversion=[LATEST_VERSION]&passkey=[API_KEY]&Filter=ProductId:[PRODUCT_ID]

JSONP

GET https://stg.api.bazaarvoice.com/data/reviews.json?apiversion=[LATEST_VERSION]&passkey=[API_KEY]&Filter=ProductId:[PRODUCT_ID]&callback=[CALLBACK_FUNCTION]

CGC requests that do not specify a single product id equality filter

Future Conversations API releases will be optimized to support displaying CGC about a single product on that product's PDP. As a result the API will be limited to returning content for one product per request. This applies to reviews, questions, answers and comments. The following examples demonstrate future compatible and incompatible requests:

Incompatible

GET https://stg.api.bazaarvoice.com/data/reviews.json?apiversion=[LATEST_VERSION]&passkey=[API_KEY]
GET https://stg.api.bazaarvoice.com/data/reviews.json?apiversion=[LATEST_VERSION]&passkey=[API_KEY]&Filter=ProductId:[PRODUCT_ID-1,PRODUCT_ID-2,PRODUCT_ID-N]

Compatible

GET https://stg.api.bazaarvoice.com/data/reviews.json?apiversion=[LATEST_VERSION]&passkey=[API_KEY]&Filter=ProductId:[PRODUCT_ID]
GET https://stg.api.bazaarvoice.com/data/reviews.json?apiversion=[LATEST_VERSION]&passkey=[API_KEY]&Filter=ProductId:eq:[PRODUCT_ID]

Altered functionality in future releases

Product and category requests that do not identify a product or category ID equality filter

Requesting products or categories without knowing the IDs in advance will not be supported in future releases of the Conversations API. As a result, paginating through multiple product or category result sets using Limit and Offset will also not be supported.

Bazaarvoice gets product and category information from our clients, so we expect that our clients have access to those IDs (because we get the IDs from them). If you are working on behalf of one of our clients, you should ask them to give you access to their IDs.

Incompatible

GET http://stg.api.bazaarvoice.com/data/products.json?apiversion=[LATEST_VERSION]&passkey=[API_KEY]
GET http://stg.api.bazaarvoice.com/data/products.json?apiversion=[LATEST_VERSION]&passkey=[API_KEY]&Limit=100&Offset=0
GET http://stg.api.bazaarvoice.com/data/categories.json?apiversion=[LATEST_VERSION]&passkey=[API_KEY]&Limit=100&Offset=100

compatible

GET https://stg.api.bazaarvoice.com/data/products.json?apiversion=[LATEST_VERSION]&passkey=[API_KEY]&filter=ProductId:[PRODUCT_ID]
GET https://stg.api.bazaarvoice.com/data/categories.json?apiversion=[LATEST_VERSION]&passkey=[API_KEY]&filter=CategoryId:eq:[CATEGORY_ID]

Product and category requests that identify multiple IDs are future compatible.

GET https://stg.api.bazaarvoice.com/data/products.json?apiversion=[LATEST_VERSION]&passkey=[API_KEY]&filter=ProductId:[PRODUCT_ID-1,PRODUCT_ID-2,PRODUCT_ID-N]

Field labels removed from display responses

Newer releases of the Conversations API will not include text labels is display responses. API consumers are encouraged to create and host labels just as they would any other aspect of their user interface. The following elements will not be populated with meaningful values in upcoming API releases:

  • Label
  • MaxLabel
  • MinLabel
  • ValueLabel

In the graphic diff below, the left side shows the response from the current version of the Conversations API and the right represents the response from a newer, not yet released version.

The above diff has been ordered to make comparison easier. You should not rely on the order of elements in the API response.

If you need to use the labels hosted by Bazaarvoice, there are several future compatible options:

  • Clients on our Conversations platform can look up field labels by logging into their Bazaarvoice portal, opening the Configuration Hub (Settings -> Manage Applications), selecting a deployment zone, and navigating to the "Submission Form Editor" tab.
  • The submission response will continue to include labels. See the Submission Fundamentals tutorial to learn how to use the submission request to get form meta-data, including field labels.
  • Contact Bazaarvoice Support to ask for the field labels.

Reduced categories.json data

Future releases of the Conversations API will return less category data than the current release. The following elements will not be populated with meaningful values in upcoming API releases:

  • Attributes
  • AttributesOrder
  • ProductIds
  • QuestionIds
  • StoryIds

In the graphic diff below, the left side shows the response from the current version of the Conversations API and the right represents the response from a newer, not yet released version.

The above diff has been ordered to make comparison easier. You should not rely on the order of elements in the API response.

Limited questions and answers statistics

Future Conversations API releases will provide less detailed question and answer statistics. The following elements will not be populated with meaningful values in upcoming API releases:

  • AnswerHelpfulVoteCount
  • AnswerNotHelpfulVoteCount
  • BestAnswerCount
  • ContextDataDistribution
  • ContextDataDistributionOrder
  • FeaturedAnswerCount
  • FeaturedQuestionCount
  • FirstAnswerTime
  • FirstQuestionTime
  • HelpfulVoteCount
  • LastAnswerTime
  • LastQuestionAnswerTime
  • LastQuestionTime
  • QuestionHelpfulVoteCount
  • QuestionNotHelpfulVoteCoun
  • TagDistribution
  • TagDistributionOrder

In the graphic diff below, the left side shows the response from the current version of the Conversations API and the right represents the response from a newer, not yet released version.

The above diff has been ordered to make comparison easier. You should not rely on the order of elements in the API response.