Raw Request API Access

A wrapper class library (DLL) is available for .NET clients to make working with the API much easier. Working with raw requests is only recommended for non-.net clients and advanced users only. If you do not wish to use the raw requests then you should read the Getting Started with Client Wrapper article instead of this guide.

Technology Requirements

To work directly with raw HTTP requests you should be familiar with how to generate GET, POST, and DELETE calls. You will need to pass in querystring parameters and post form values to specific URLs.

You should be familiar with and able to generate valid JSON data as a string to be posted to URLs and able to read back JSON values to consume the results of requests.

GET Requests

Use GET requests passing in the API key as a ?key={MyKeyHere} querystring parameter to retrieve objects. Results are wrapped in an ApiResponse object which has a list of zero or more ApiErrors and a Content object which contains that actual item requested. An example of a JSON response from a request for a list of categories is below:

{"Errors":[],
 "Content":[
    {
      "Bvin":"1596f128-192a-46b6-b379-206b0ebed659",
      "StoreId":1,
      "ParentId":"0",
      "Name":"A Category Name",
      "SourceType":0,
      "ImageUrl":"BVLogo_2009_OnWhite_140x60.png",
      "LatestProductCount":0,
      "CustomPageUrl":"",
      "CustomPageOpenInNewWindow":false,
      "ShowInTopMenu":false,
      "Hidden":true,
      "CustomPageId":"",
      "CustomPageLayout":0,
      "RewriteUrl":"a-category",
      "SortOrder":1,
      "MetaTitle":"",
      "Operations":[]
    },
    {
      "Bvin":"c31a0553-8917-4c6e-b0eb-cadde065aec9",
      "StoreId":1,
      "ParentId":"0",
      "Name":"My Sample Content Page",
      "SourceType":3,
      "ImageUrl":"",
      "LatestProductCount":0,
      "CustomPageUrl":"",
      "CustomPageOpenInNewWindow":false,
      "ShowInTopMenu":false,
      "Hidden":false,
      "CustomPageId":"",
      "CustomPageLayout":5,
      "RewriteUrl":"my-sample-content-page",
      "SortOrder":2,
      "MetaTitle":"Sample Meta Title",
      "Operations":[]
    }
   ]
}

Here is the raw HTTP Request used to get the response above:

GET http://localhost/api/rest/v1/categories?key=1-3a5bc725-2f64-857a-54bc-137e70eefd17 HTTP/1.1
Host: localhost
User-Agent: Mozilla/5.0 (Windows NT 6.1; WOW64; rv:9.0.1) Gecko/20100101 Firefox/9.0.1
Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
Accept-Language: en-us,en;q=0.5
Accept-Encoding: gzip, deflate
Accept-Charset: ISO-8859-1,utf-8;q=0.7,*;q=0.7
Proxy-Connection: keep-alive

POST and DELETE Requests

POST and DELETE requests should be very similar to GET requests but instead of passing values in the querystring, values are passed as posted form data.

SSL / HTTPS

We recommend that all API calls be sent over HTTPS/SSL to help protect your API key

What's Next

You'll want to review the API Reference Guide for a complete list of URLs, and items available in the API.