Remix URL Tutorial

This tutorial explains the components that make up the Remix URL and how to use them when constructing your URL.

Topics covered:

Remix URL Component Breakdown
Types
Filtering
Parameters

Remix URL Component Breakdown

Remix URLs have several components. For example, the following URL has 7 distinct parts:

http://api.remix.bestbuy.com/v1/products(manufacturer=nikon&salePrice>200)?sort=RegularPrice.desc&apiKey=<YourApiKey>

• http://api.remix.bestbuy.com/ - This is the base Remix URL, which is always present.
• v1/ - This is the version of the API which you are querying.  Using this, you can have a stable base to build on, even as the api evolves. v1 is the current version of the API, and the one described in these documents.
• products - This is the query type, and indicates what sort of information you're requesting.  Remix supports 2 types: stores and products.  You can also join the two to view information about store availability.
• (manufacturer=nikon&salePrice>200) - This is a filter applied to the type you request.  In this case, the above query will only return products that are manufactured by nikon and have a price greater than $200.
• ?sort=RegularPrice.desc - There are a number of additional parameter which you may specify in your query which will further adjust the results, for example, sorting them, or limiting which attributes are displayed.
• &apiKey=<YourApiKey> - You apiKey grants you access to the Remix service.  You'll need to include it with every request.

We'll now go over each of the meaningful components in turn: type, filter, and parameters.

Back to Top

Types

Remix currently includes 2 types of information: stores and products.  Please review the separate Products and Stores documentation pages for type-specific information on queries.  The information below holds for both.

Also, "store availability" information is available by "joining" the store and product types.  Look to the Store Availability page for details on constructing these queries.

Attributes

An attribute is a value associated with a product or store.  For example, products have a listPrice attribute which carries their purchase price.  Each attribute is represented in the results as an XML node or a JSON value. For example, if a certain product has a listPrice attribute equal to 14.99, the xml node for the attribute would be <listPrice>14.99</listPrice> and the JSON value would be {"listPrice": 14.99}.

Attributes are the values by which the query can be sorted, filtered and returned

Back to Top

Filtering

You can filter both products and stores using comparisons with their attributes.  Several comparison types are supported:

• equal/not equal: /products(salePrice=11.99)  /products(salePrice!=11.99)  /products(salePrice<>11.99)
• wildcard: /products(name=bat*)
• less/greater numeric: /products(salePrice<11.99)    /products(salePrice<=11.99)  /products(salePrice>11.99)    /products(salePrice>=11.99)
• less/greater date: /products(itemUpdateDate<2008-09-03)   /products(itemUpdateDate>2008-06-11)
• and: /products(name=bat*&salePrice<20)

Here's an example of a call involving a filter and it's result.

URL: http://api.remix.bestbuy.com/v1/products(manufacturer='canon')?apiKey=<YourApiKey>

Result:
<products currentPage="1" totalPages="45" from="1" to="10" total="443">
  <product>
    <sku>446789</sku>
    <name>Red Canon Ink</name>
    <type>HardGood</type>
    <manufacturer>Canon</manufacturer>
  </product>
  ...(8 other products)
  <product>
    <sku>444001</sku>
    <name>S500 Digital Camera</name>
    <type>Hardgood</type>
    <manufacturer>Canon</manufacturer>
    ... (other attributes)
  </product>
</products>

Combining Filter Conditions

Multiple filter conditions can be combined in a single query, using the & (AND) and | (OR) operators. In the following example, all the returned products have both a manufacture named "canon" and a price less than $33:

URL: http://api.remix.bestbuy.com/v1/products(manufacturer='canon'&salePrice<33)?show=name&sort=regularPrice&apiKey=<YourApiKey>

Result:

<products currentPage="1" totalPages="5" from="1" to="10" total="47">
  <product>
    <name>Black Canon Ink</name>
  </product>

  ...(8 other products)

  <product>
    <name>Red Canon Ink</name>
  </product>
</products>

Back to Top

Parameters

Result paging / record position

Results are returned in groups of 10.  Your current position in the set of pages that results from your query is shown in attributes of the root of the document, like so:

Example: <products currentPage="2" totalPages="5" from="11" to="20" total="47">

In this example, the results shown would be from page 2.  There are five total pages totaling 47 records.  The product records shown are numbers 11 to 20.

Example: <products currentPage="5" totalPages="5" from="41" to="47" total="47">

Note that in this example we're on the last page, and you'd see 7 records only (rather than the normal 10) because we're at the end of the set.

URL: http://api.remix.bestbuy.com/v1/products?page=3&apiKey=<YourApiKey>

Result:
<products currentPage="3" totalPages="37600" from="21" to="30" total="376001">
  <product>
    <sku>100021</sku>
    <name>Batman</name>
    <type>Movie</type>
    ... (other attributes)
  </product>
  ...(8 other products)
  <product>
    <sku>100020</sku>
    <name>Oven</name>
    <type>HardGood</type>
  </product>
</products>

Show only certain attributes:

Result sets can be large, and transmitting unnecessary data means slower responses.  You can use the "show" parameter to restrict the display of attributes to only those specified.  For example:

URL: http://api.remix.bestbuy.com/v1/products?show=sku,url&apiKey=<YourApiKey>

Result:
<products currentPage="1" totalPages="37600" from="1" to="10" total="376001">
   <product>
     <sku>100001</sku>
     <url>http://www.bestbuy.com/site/olspage.jsp?skuId=8800577&type=product&id=1205538350143</url>
   </product>
   ...(8 other products)
   <product>
     <sku>100010</sku>
     <url>http://www.bestbuy.com/site/olspage.jsp?skuId=8800577&type=product&id=1205538350143</url>
   </product>
</products>

Sort:

You can use the "sort" parameter to have the result sorted by one of their parameters.  Adding ".desc" will result in a descending sort, where the highest values come first:

URL: http://api.remix.bestbuy.com/v1/products?sort=name.desc&apiKey=<YourApiKey>

Result:
<products currentPage="1" totalPages="37600" from="1" to="10" total="376001">
  <product>
    <sku>778899</sku>
    <name>Zeppelin</name>
    <type>Music</type>
    ... (other attributes)
  </product>
  <product>
    <sku>887766</sku>
    <name>Zappa</name>
    <type>Music</type>
  </product>
  ...(7 other products)
  <product>
    <sku>225577</sku>
    <name>Zany People</name>
    <type>Movie</type>
  </product>
</products>

Back to Top