Best Buy Remix Developer Blog

Well, we've been talking about it for a while...so we've finally gone and done it, we've versioned the API. Below are Steve's release notes on what's been changed...but the most important thing to note is that we are now at version 1. Previous to this we were, well, version nothing, I guess. Now, to access the API you need to hit http://api.remix.bestbuy.com/v1/products...

Check out what we've done...and please comment away!

Dave

-----------------

- API versioning:
  - /products refers to /v0/products
  - /v1/products refers to the new version of the api
  - we will stop supporting /v0/products and /products soon.  For new development, always use /v1 urls

- Image urls are now available for almost every product (not just type=hardgood)

- Query improvements:
  - "or" works: (manufacturer=canon|manufacturer=nikon)
  - grouping/nesting works:
((manufacturer=canon|manufacturer=nikon)&salePrice<30)
  - we handle values with &'s and such  (name='Batman & Robin')
  - wildcard searches are improved.  (name=begins*) now matches "Batman Begins" - i.e. we match words in the middle of a string of words, not just at the beginning.
  - you can now use one-to-many attributes in a query, e.g.
/v1/products(cast.name='Tom Cruise')
  - fixed: if you fail to encode spaces with a '+' (plus sign) inside your product filters you will get an error page.
  - you can query by time on attributes where that's appropriate, ex:
/v1/products(itemUpdateDate>2008-10-20T11:20:00&itemUpdateDate<2008-10-20T13:15:45)
  - We show only active products by default - that is, all queries are constrianed by active=true, UNLESS you explicitly use the active attribute in a query.  So for instance:
    - to get all active products: /v1/products(active=true), which, because of defaulting, is equivalent to /v1/products
    - to get all inactive products: /v1/products(active=false)
    - to get both active and inactive products:
/v1/products(active=false|active=true) ...this is necessary to override the defaulting.
  - Fixed a bug where you couldn't use dates before 1970 in a query.
So to get all music originally released in the 60's:
/v1/products(type=music&originalReleaseDate>=1960-01-01&originalReleaseDate<1970-01-01)

- Categories are now available in a structured form:

<categoryPath>
    <category>
        <id>cat00000</id>
        <name>Best Buy</name>
    </category>
    <category>
        <id>abcat0600000</id>
        <name>Music & Movies</name>
    </category>
    <category>
        <id>cat02015</id>
        <name>Movies</name>
    </category>
    <category>
        <id>cat02016</id>
        <name>Action & Adventure</name>
    </category>
    <category>
        <id>cat02017</id>
        <name>Action</name>
    </category>
</categoryPath>

  ...you can make a corresponding query:
    /products(categoryPath.category.name='Action & Adventure')
   or
    /products(categoryPath.category.id=cat02016)

  ...consequently, categoryIdPath has been dropped


- in /v1, 'buyUrl' is renamed to 'url'

- New product attributes:
  - active
  - activeUpdateDate
  - offers
  - priceUpdateDate
  - addToCartUrl
  - upc
  - inStoreAvailabilityUpdateDate
  - onlineAvailabilityUpdateDate

- We now expose time information for attributes where that's appropriate.  Previously we were only showing the date information.
So for instance itemUpdateDate values previously looked like "2008-10-20", now they look like "2008-10-20T23:20:50". Querying works too. So you can do
/v1/products(itemUpdateDate>2008-10-20T23:20:49&itemUpdateDate<2008-10-20T23:20:51)
to retrieve the above product.

- Non-truncated results are returned for all attributes. Formerly, these were limited to 256 characters for description, long-description, plot, etc.

- affiliate url's: if you provide "ref" and "loc" query parameters, the api will generate affiliateUrl and affiliateAddToCartUrl for each product
  /v1/products/8880044.xml?ref=88&loc=99 gets you
   <affiliateUrl>
      http://www.bestbuy.com/site/olspage.jsp?skuId=8880044&type=product&id=1484301&ref=88&loc=99
   </affiliateUrl>

   and

   <affiliateAddToCartUrl>
      http://www.bestbuy.com/site/olspage.jsp?id=pcmcat152200050035&type=category&ref=88&loc=99&qvsids=8880044
   </affiliateAddToCartUrl>

- error messages are more helpful
  /v1/products/8880044.xml?show=foo
  /v1/products(foo=1)
  are examples of bad urls that give you information about what went wrong and what to do differently.

- There are some product attributes we don't display by default.  Use show=all to see all product attributes.

- The product catalog is updated every two hours (the most important update period, incidentally, is around noon CT)

- All times are CT

- In /v1, JSON date and time formats have changed from milliseconds since 1970, to string-formatted dates as in the xml.