Platform & API Concepts

This page explains important concepts that you need to know in order to use the Conversations Platform and API.

Anatomy of an API request

All requests to the Conversations API will include the following components:

http[s]://{environment}/data/{contenttype}.{json|xml}?ApiVersion={n.n}&Passkey={apikey}
URL componentDescription
Protocolhttp[s]The Conversations API supports both http and https. We recommend using https for all requests. See Secure requests below for more information.
Domain{environment}This token will be replaced with stg.api.bazaarvoice.com or api.bazaarvoice.com depending on which environment you wish to serve your request. Continue to Environments below to learn more.
PathdataOur CDN uses this section to route requests to the Conversations API application servers.
{contenttype}Used to identify which content type you would like to request or submit. Learn more at Display Fundamentals and Submission Fundamentals.
{json|xml}The Conversations API currently supports both JSON and XML.

:warning: Using xml is prohibited by our Conversations API Terms of Use - 4.Requirements and has been disabled for API keys issued after August 29th, 2016.
Query StringsApiVersion={n.n}Identifies which version of the API will process your request. You should always use the latest version. Continue to Versioning below to learn more.
Passkey={apikey}API keys are used to identify which client's data should be returned and are used for tracking and metrics. To learn how to get API keys read Key request process.

📘

The Conversations API supports many other options in addition to those listed above. Continue to the Display Fundamentals and Submission Fundamentals sections to learn more.

Secure requests

When a secure request is made using the HTTPS protocol, the following assets are returned with a secure scheme:

  • Bazaarvoice-hosted photos
  • Bazaarvoice-hosted syndication attribution values
  • YouTube URLs

Other assets, like those imported into the Bazaarvoice platform via a product feed, are not altered when a secure request is made. For example, product image URLs using HTTP, provided to Bazaarvoice using a feed, will not be upgraded to HTTPS.

Environments

The Conversations API supports the following environments:

Staging
Domainstg.api.bazaarvoice.com
DescriptionUsed while developing your application. Content submitted to this environment will be automatically published approximately every 15 minutes. Staging is virtually identical to production in implementation, but not scale. Please do not attempt load testing in staging.
Production
Domainapi.bazaarvoice.com
DescriptionUsed when your application is complete. Content submitted to this environment will be manually moderated in 72 business hours or less. Please contact us if you would like to do automated performance testing, such as load testing or security scans, against production.

Versioning

The Bazaarvoice Conversations API is versioned so that we can release new features, bug fixes and improvements without compromising the stability of applications using the API.

This table shows all Conversations API versions.

Version* First Release Deprecation Date Status
Beta (PRR) Invite only August 2011 Deprecated
4.9 (PRR) August 2011 April 30th, 2016 Deprecated
5.0 (PRR) October 2011 April 30th, 2016 Deprecated
5.1 (PRR) February 2012 April 30th, 2016 Deprecated
5.2 (PRR) June 2012 April 30th, 2017 Deprecated
5.3 (PRR) August 2012 April 30th, 2017 Deprecated
5.4 (PRR) January 2013 Undetermined Latest
5.4 (Conversations) August 2016 Undetermined Latest

*Refer to the Upgrade Guide and Changelogs to learn more about the differences between versions.

Deprecated

These versions should not be expected to return data and/or may experience service degradation. Documentation specific to these versions may no longer be available. Bazaarvoice will provide one year advance notice before deprecating an API version.

Sunset

A deprecation date has been announced for these versions. Until that date they will continue to function. Applications using these versions should be upgraded to the latest version before the deprecation date to ensure continued functionality. New applications should NOT use these versions.

Active

Active versions continue to function, but applications using these versions should be upgraded to the latest version when possible to take advantage of new features and bug fixes. New applications should NOT use these versions.

Latest

This is newest version. Feature development is focused on future versions, but we may perform backwards compatible bug fixes. New applications SHOULD use this version.

Platforms

The API features you can use are dependent on your platform. The Conversations PRR platform has access to some features not available to Conversations platform.

Conversations PRR

This is the first Conversations platform. Originally called "Product Rating and Reviews" and later shortened to "PRR". On this platform client configurations are internal and all changes must be done by Bazaarvoice personnel. This platform is not available to new clients.

Conversations

Conversations is our latest platform. For this platform we've focused on best practices learned through our experience with the previous platform. This platform supports new features as well as the most valuable features from Conversations PRR, while eliminating poorly adopted or low value functionality. Clients on this platform have access to our self-service Configuration Hub, allowing them to see and interact with their configurations without relying on Bazaarvoice personnel.

Clients provisioned after mid 2013 are not likely to be on Conversations PRR and many older clients have already opted to migrate to Conversations.

Feature availability and configuration

The Conversations API exposes a large number of features spread across several platforms. There are nine content types and over 30 different field types. Many of these are configurable, meaning their behavior and properties can be different from client to client. As a result, the features you see described in the Developer Portal may need additional configuration, may need to be enabled by default, or may not be available to you at all.

We understand that figuring out what features are available and how they are configured is challenging, so we've provided some tools to help:

The API submission response

The API itself can be used to introspect available fields by omitting the Action parameter in a submission request. Learn more at the Submission Fundamentals tutorial.

Conversations API Inspector

The API Inspector helps you see what fields are available for submission. The API Inspector makes a request without the Action parameter and displays the results in an easy to understand GUI. Open the Conversations API Inspector.

Configuration Hub

If you are on the Conversations platform, you have access to a self-service configuration UI allowing you to see and interact with your configurations. Open Configuration Hub to navigate to the Configuration Hub.

Bazaarvoice Support

If the above options don't work for you, then we can help.

Future compatibility

We're thinking about the future of the Conversations API and we want you to be prepared. This section will help you to build applications with our Conversations API that are easier to upgrade to future API releases.

In the context of the Conversations API, future compatibility means gracefully accepting API responses generated by future API releases. A future compatible application is one that requires minimal code change to move to a newer API release.

How to improve future compatibility

  1. Always use the latest Conversations API version

    • We try to make each API release as backwards compatible as possible with the previous version. By using the latest version you can increase the likelihood that your application will work with newer API releases or at least minimize the work needed to upgrade.

      See Versioning above for more details.

  2. Do not use Conversations PRR only features, even if you are still on the Conversations PRR platform

    • Conversations PRR only features are no longer supported on our newest Conversations platform. You should not expect them to be available in new API releases.

      See Conversations PRR Only Features for a complete list.

    • Try to avoid using features which we plan to deprecate in the future. These features are marked with a warning and are fully documented at Future deprecations.

  3. Try to avoid using features which we plan to deprecate in the future. These features are marked with a warning and are fully documented at Future deprecations.