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}

📘

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:

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.

*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.