Category Archives: General Announcements

Conversations API Deprecation for Versions 4.9, 5.0 and 5.1, and Custom Domains

This blog post only applies to the Conversations API and does not apply to any other Bazaarvoice product. You are able to identify the Bazaarvoice Conversations API by the following:

  • Path includes ‘data’: http://api.bazaarvoice.com/data/reviews.json?

Code related to the Bazaarvoice Hosted Display does not need modification. It can be identified by the following:

  • References ‘bvapi.js’: http://display.ugc.bazaarvoice.com/static/ClientName/en_US/bvapi.js

Still unsure if this applies to you? Learn more.

Today we are announcing two important changes to our Conversations API services:

  • Deprecation of Conversations API versions older than 5.2 (4.9, 5.0, 5.1)
  • Ending Conversations API service using custom domains

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

Our newer APIs and universal domain system offer you important advantages in both features and performance. In order 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 feel offer the most benefits to our customers. Please visit our Upgrade Guide to learn more about the Conversations API, our API versioning, and the steps necessary to support the upgrade.

We understand that this news may be surprising. This is your first notification of this change. In the months and weeks ahead, we will continue to remind you that this change is coming.

We also understand that this change will require effort on your part. Bazaarvoice is committed to making this transition easy for you. We are prepared to assist you in a number of ways:

  • Pre-notification: You have 12 months to plan for and implement the change.
  • Documentation: We have specific documentation to help you.
  • Support: Our support team is ready to address any questions you may have.
  • Services: Our services teams are available to provide additional assistance.

In summary, on April 30, 2016, Conversations API versions released before 5.2 will no longer be available. Applications and websites using versions before 5.2 will no longer function properly after April 30, 2016. In addition, all Conversations API calls, regardless of version, made to a custom domain will no longer respond. Applications and websites using custom domains (such as “ReviewStarsInc.ugc.bazaarvoice.com”) will no longer function properly after April 30, 2016. If your application or website is making API calls to Conversations API versions 4.9, 5.0 and 5.1 you will need to upgrade to the current Conversations API (5.4) and use the universal domain (“api.bazaarvoice.com.”). Applications using Conversations API versions 5.2 and later (5.2, 5.3, 5.4) with the universal domain will continue to receive uninterrupted API service.

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

Thank you for your partnership,
Chris Kauffman
Sr. Product Manager

Jolt Command Line Interface

Some of y’all may have caught our previous blog post announcing the release of our Java JSON transformation library, Jolt.

Jolt is a powerful tool that can accomplish a variety of useful transformations on JSON data, and even chain multiple transformations together. Jolt has additional functionality that is useful for working with JSON including the ability to intelligently diff JSON documents and sort JSON documents. Users of Jolt can now transform, diff and sort JSON via the command line using the Jolt CLI. The CLI even allows you to string multiple commands together via standard in:

curl -s "http://some.host.com/stuff/data.json" | jolt sort | jolt diffy moreData.json 

The Jolt CLI supports the following sub-commands:

Diffy

The Jolt Diffy sub-command is an excellent way to compare JSON documents at the command line. It gives you a lot of friendly human-readable output, or you can have it run silently and examine the exit code to determine if any differences were found.

Have you ever tried using diff to detect differences in a JSON document? Due to the nature of JSON data the regular diff command can sometimes be inadequate. For Example, consider the following two JSON documents:

diff1.json

{
  "someData": "dude",
  "moreData": "sweet"
}

diff2.json

{
  "moreData": "sweet",
  "someData": "dude"
}

Running the diff command from the command line returns the following:

user@computer:~/Projects/blog-post$ diff diff1.json diff2.json
2,3c2,3
< "someData": "dude",
< "moreData": "sweet"
---
> "moreData": "sweet",
> "someData": "dude"

This really isn’t helpful. Since the example data is in the form of a map, then two documents are essentially equal. However, because the entries are ordered differently, diff detects differences. Diffy ignores the ordering of map entries:

user@computer:~/Projects/blog-post$ jolt diffy diff1.json diff2.json
Diffy found no differences

Diffy does a recursive tree walk to find differences throughout the JSON document, so it can detect differences N levels deep.

diff3.json

{
  "aMap": {
    "stuff": "yeah"
  },
  "someData": "whatever",
  "matchingData": "cool"
}

diff4.json

{
  "aMap": {
    "differentStuff": "woah"
  },
  "differentData": "bleargh",
  "matchingData": "cool"
}
user@computer:~/Projects/blog-post$ jolt diffy diff3.json diff4.json
Differences found. Input #1 contained this:
{
  "someData" : "whatever",
  "aMap" : {
    "stuff" : "yeah"
  }
}
Input #2 contained this:
{
  "differentData" : "bleargh",
  "aMap" : {
    "differentStuff" : "woah"
  }
}

Diffy does flag differences in array ordering. Consider the following two JSON documents:

array1.json

{
  "arrayData": [
    "one",
    "two",
    "three",
    "four"
  ]
}

array2.json

{
  "arrayData": [
    "one",
    "three",
    "two",
    "four"
  ]
}

Diffy detects the differences in the array:

user@computer:~/Projects/blog-post$ jolt diffy array1.json array2.json
Differences found. Input #1 contained this:
{
  "arrayData" : [ null, "two", "three", null ]
}
Input #2 contained this:
{
  "arrayData" : [ null, "three", "two", null ]
}

If for some reason you are crazy (like some of us at Bazaarvoice) and you want to ignore array order, you can use the -a flag for those occasions.

Transform

The Jolt Transform sub-command allows you to perform transforms on JSON documents provided via standard in or file. Transform also takes a spec, which is a JSON document that contains one or more Jolt specs to indicate what transformations should be done on the document. Transform has the option to produce the results with or without pretty print formatting.

You can read more about Jolt transforms here.

Sort

The Jolt Sort sub-command will sort JSON input. The sort order is standard alphabetical ascending, with a special case for “~” prefixed keys to be bumped to the top. This can be useful for debugging when you need to manually inspect the contents of a JSON document. Sort has the option to produce the results with or without pretty print formatting.

That does it for today. Hopefully you have an idea of what the Jolt CLI does in broad strokes. If you’re curious about Jolt, you can read much more about it here.

Conversations API Inspector

An all too familiar scenario

Imagine you’re a developer working for Widgets n’More. The marketing team just came up with a new cross platform social media promotion. It’s going to involve collecting user generated content in the form of ratings and reviews. As luck would have it you remember your friend on the Ecom Team had mentioned working with a company called Bazaarvoice last year. Widgets n’More partnered with Bazaarvoice specifically for the purpose of collecting and displaying reviews.

In short order you find yourself at developer.bazaarvoice.com where you start reading the Conversations API documentation. There are a lot of fields and parameters and content types. What’s more, some of them appear to be customizable. They offer custom rating fields, tags, context data questions, and additional free text fields. One company might have “rating_value” while another might be using “rating_quality”. It’s also not immediately clear how any those should be displayed in a webform. The fields can even have customizable properties like min and max length.

So, you call your friend hoping she’ll be able to shed some light on the situation. She explains that Bazaarvoice can even configure fields based on content type, like reviews, questions or answers, and make different custom fields available depending on the parent category of a product. Unfortunately it’s been so long since the initial Bazaarvoice implementation that she doesn’t remember what was set up. If only there was an easy way for you to see exactly what fields are available taking all those factors into account…

Conversations API Inspector to the rescue

The Conversations API Inspector was created with the above scenario in mind. It is a web based app that shows what fields can be submitted to the Bazaarvoice platform using the Conversations API for any API key + content type + ID combination. With the Conversations API Inspector our imaginary developer would be able to see what fields are available, how they must be submitted in an HTTP request, meta-data about each field and much more

The Conversations API Inspector is ready to use and publicly available at http://api-inspector.bazaarvoice.com/. It is well documented at our Developer Portal, so instead of repeating that here I’ll leave you with some screenshots.

noHistory topNoFields topWithFields
fields fieldDetailsProperties fieldDetailsSubmission

Epilogue

Even without the Conversations API Inspector all would not have been lost for our imaginary developer. He could have used the API itself to determine what fields are available. In fact this is exactly how the Conversations API Inspector does it. Of course, the Inspector provides a much more user friendly and interactive GUI than the raw JSON or XML returned by the Conversations API. You can read more about how the inspector works at the documentation under the heading “How it works”.

Maintenance Notice: Bazaarvoice Developer Portal

We’ll soon be giving our Developer Portal some love in the way of functionality and style updates. To facilitate this, we’ll be taking the portal offline for approximately 6 hours on Thursday, August 15th; the estimated times are listed in a few timezones below:

Timezone Start date/time End date/time
UTC Thursday, August 15, 2:00 AM Thursday, August 15, 8:00 AM
EDT Wednesday, August 14, 10:00 PM Thursday, August 15, 4:00 AM
PDT Wednesday, August 14, 7:00 PM Thursday, August 15, 1:00 AM
AEST Thursday, August 15, 12:00 PM Thursday, August 15, 6:00 PM
IST Thursday, August 15, 7:30 AM Thursday, August 15, 1:30 PM

Bookmarks to existing documentation will work through at least part of the downtime, but please excuse any styling inconsistencies as we work through the update.

If you need something quickly, tweet us @BazaarvoiceDev and we will do our best to get you the assistance you need.

Thanks for your patience!

Jolt released to the world

We are pleased to announce a new open source contribution, a Java based JSON to JSON transformation tool named Jolt.

Jolt grew out of a BV Platform API project to migrate the backend from Solr/MySql to Cassandra/ElasticSearch.  As such, we were going to be doing a lot of data transformations from the new ElasticSearch JSON format to the BV Platform API JSON format.

Prior to Jolt, there were 3 general strategies for doing JSON to JSON transforms :

  1. Convert to XML, use XSLT, convert back to JSON
  2. Use your input JSON and a template language to build your output JSON
  3. Write custom code

Those options were rather unpalatable, so we went with option “4”, write reusable custom code.

The key insight was that there are actually separable concerns when doing a transform, and that part of the reason the XSLT or template approaches are unpalatable, is that they force you to deal with them all together.

Jolt tackles each separate concern individually :

  1. Identify the pieces of the input data that you care about and place them in the output JSON
    • Jolt provides a transform, “shift”, that has its own JSON based declarative DSL (domain specific language)
  2. Make sure the output JSON looks correct ( apply defaults to the output JSON )
    • Jolt provides a transform, “default”, with its own JSON based declarative DSL
  3. Handle all the JSON text formatting (comma, closing curly brackets etc)
    • Jolt operates on “hydrated” JSON data (Map<String,Object> and List<Object>) and leverages the Jackson library to handle serialization / JSON text formatting
  4. Verify the transform for data and format correctness
    • Jolt provides a test tool called Diffy so that you can unit test your transforms for data and format correctness
    • For format correctness, this is not as good of an answer as an xml dtd is, but you could pull in the JSON schema if you wanted
  5. Perform arbitrary custom data manipulations like adding fields together or performing date conversions
    • Jolt provides an interface where you can implement your own custom logic to be run in series with the other transforms

The code is now available at Github, and jar artifacts are now being published to Maven central.

Mashery-powered Bazaarvoice Developer portal is LIVE!

Welcome to the Mashery-powered Bazaarvoice Developer portal. We strive to give you the tools you need to develop cutting-edge applications on the Bazaarvoice platform.

Some changes you’ll notice:

  • You no longer have to login to see documentation. Just click the Expand icon (expand) to drill down to the information you need.
  • If you want to request an API key or need to contact us with a support question, you will need to create and use a Mashery ID (or use your existing one if you access other Mashery-powered APIs). Your current Bazaarvoice developer portal ID will no longer work.

Note that none of your existing API keys are affected by this transition. They will continue to work without interruption.

Thanks for your support of the Bazaarvoice platform.

Bazaarvoice developer portal moving to Mashery effective 3/1/13

We are pleased to announce that on March 1, 2013, we are moving our developer portal hosting to Mashery.

What does this mean to you, our developer community:

  • None of your existing API keys will be affected by this transition. They will continue to work without interruption.
  • You no longer need to log in to see API documentation or any public content on the site.
  • To request a new API key, you will need to register with a Mashery ID (or use your existing one if you access other Mashery-powered APIs). Your current Bazaarvoice developer portal ID will no longer work after March 1st.
  • There is no change to the developer portal URL (http://developer.bazaarvoice.com).

We know that the increased security and faster key generation will enhance your development experience. As always, thank you for developing on the Bazaarvoice platform. We look forward to seeing your applications.