Check out our new & improved API documentation here, complete with request examples, response examples and much more. 

Resource Response Formats

JSON is our default format. Its our favourite format and expresses the data closest.

E.g. /product/1.json →

{"name":"demo product", … }

JSONP, all you need to do to use this format is to request the json format and supply a callback in the url. This format is great for getting around Cross-domain Security in javascript.

E.g. /product/1.json?callback=myFunc →

myFunc({"name":"demo product", … });

XML format is available too if you prefer.

E.g. /product/1.xml →

<?xml version="1.0" encoding="UTF-8"?>
<root>
    <name>demo product</name>
</root>

PHP print_r format is available for debugging purposes.

E.g. /product/1.php →

stdClass Object 
( 
    [name] => demo product 
)

To help with reading the data, we also offer nicer formatted versions of the JSON, and XML formats, all you need to do is in the url, set prettyPrint=true (but for production you will want the minimized version for speed).

E.g. /product/1.json →

{"name":"demo product", … }

E.g. /product/1.json?prettyPrint →

{
    "name": "demo product",
    …
}

Push Notifications Response Formats

Available in JSON or XML, either as raw post data or in a key=value param style like form-urlencoded data.

Resource naming convention

We will be using all plurals for the resource names to keep consistency, also it makes the most sense when talking about collections such as a collection of coupons, and when accessing individual objects/elements such as coupons/:code it's still obvious you are dealing with that specific one. Also dashes separate words in resource names.

The common response value “href”

This response value is present in every resource, and sub resources. It creates the linking structure of all requests.

The only places where a href value will not be present is inside error packets or some debug packets.

The href value should not be filtered by the later described expand or field params.

HTTP methods/verbs

Generally we follow a REST styled pattern for these, e.g. we use GET for listing all, or getting a specific resource. Most operations for creating something use POST. Updating is currently done with POST (PATCH also points to this). Removing a resource uses DELETE.

Different methods act on different URL's differently, full docs on these are provided.

Paging results

Most responses will be limited to 25 results (any differences will be specified alongside the method). You can then page across these results using our “limit” and “offset” url parameters. These allow you to set how many results to show (the limit param), and the offset number to start from (the offset param).

e.g. to show the first 50: http://store.com/api/v1/products.json?limit=50

then to show the next 50, etc. http://store.com/api/v1/products.json?limit=50&offset=50 http://store.com/api/v1/products.json?limit=50&offset=100 http://store.com/api/v1/products.json?limit=50&offset=150 …

Force a http method through a GET request

We are aware some clients may have trouble making certain types of requests because of the methods used by them. So by passing the force_method url param you can perform requests via GET for POST and DELETE. e.g. http://store.com/api/v1/coupons/xhS76?force_method=DELETE Available methods to force: (GET not mentioned as it would be the one used instead)

  • POST
  • DELETE

Speed testing

Internal use, adding ?speedTest=true will enable a “completedInTime” value to be added to all requests showing the seconds it took to show the resource.

Date format

ISO 8601 - Complete date plus hours, minutes and seconds (http://www.w3.org/TR/NOTE-datetime & http://en.wikipedia.org/wiki/ISO_8601)

e.g. YYYY-MM-DDThh:mm:ss

 2012-02-12T15:19:21

Encoding

UTF-8 is used.

Returning all fields

By default, the collections oftern just return subsets of the sub objects. e.g. for the users collection, you'll see each users email etc, but no addresses and other detail. These other details are found on the subobjects themselves if you make a request direct to them.

But some times you may need these extra details, and so you can use the “fields=*” url param which will return all details on each sub object ina collection. This is implimented on all resource collections.

Alternative identifiers

By default resources are identified by the id, (e.g. GET /users/ID.json, and on POST /users.json, sub user objects would be inserted / updated by the id property).

But on some resources you can set custom identifiers:

  • Products: code, name
  • Users: membership_code, email
  • Orders: invoice_id