›

Resources Available via the API

Some important points to note about resources:

A resource identified by a URI can identify either a list of items (e.g orders) or a single item (e.g. a single order).
If the URI identifies a list of items, in order to limit bandwidth usage the items are returned in chunks. When the list of items is large, the client application will have to issue several requests in order to fetch all of the chunks. When using the HTTP GET method to fetch a list of items, the following two parameters can be used to specify which chunk to fetch:

offset
A zero-based offset from the start of the list identifying which item to begin the chunk with. Defaults to zero if not specified.
limit
The maximum number of items to return in this chunk. Defaults to 20 if not specified.
For list resources, filters can also be specified to the returned items. More on this below.
The response content for a GET request on a list resource, will have two parts:
- A part named 'meta' which contains meta-data about the chunk fetched, including the total_count of items available.
- A part named 'objects' which contains a list of the individual items in the chunk. Each individual item in the list will also contain an attribute name 'resource_uri' whose value is the URI which the client can use to address that item as a resource.
At the lowest level, single item resources correspond to individual records in a database. In order not to overcomplicate the authorization process for the user, the resources are grouped into a set which is authorized as a whole.

Data Formats

The API supports several data exchange formats, as mentioned in the individual resource URIs below. The default format is json. The format can be specified as a request query string parameter with the name 'format' and the required format as value (case sensitive), e.g. http://.../?format=json

Dates will in ISO 8601 YYYY-MM-DD format

Times will in ISO 8601 hh:mm:ss format and may also have a decimal part after the seconds.

Date-time values in ISO 8601 YYYY-MM-DDThh:mm:ss format and may also have a decimal part after the seconds.

Resource Sets

Various resource types are grouped together into resource sets for the purposes of authorization. When granting approval for an application, the resource owner is granting approval for an application to access one or more listed resource sets (Resources). This coarse level of granularity is done to prevent the authorization system becoming too unwieldly for the user. Resource sets themselves can be hierarchical, whereby a permission granted to a higher level resource set is implicitly granted to all lower level resource sets. For example, by granting read access to his/her affiliate account, the resource owner is also granting the application read access to his/her affiliate feeds.

When a developer is registering an application, the resource sets (Resources) to be accessed and associated permissions required are declared. When, as part of the authorization process, the resource owner is asked to grant the application access, he/she can see which resources the application is seeking to access and what type of access (permissions) it requires.

For more information on the API-accessible resources see the following documents:

Filters

Filters can be used when fetching list resources to select only those items matching certain criteria which the filter parameters specify. Filters are applied as parameters to the GET request, typically as urlencoded (percent encode) name-value pairs in the query string. Multiple filters can be applied to a single request, and they apply in an 'AND' fashion. The name part consists of the field name to filter on, followed by a double underscore '__' followed by a comparison code. The following comparison codes are available:

Code	Description
exact	Exactly equals
gt	Greater than (or since for dates and time values)
gte	Greater than or equals (on/at or since for dates and time values)
lt	Less than (or earlier for dates and time values)
lte	Less than or equals (on/at or earlier for dates and time values)

For example, the filter dateCreated__gte=2012-04-01 will retrieve items with a dateCreated value on or since the 1st of April 2012.

If the filter name does not contain the double underscore and comparison code, the 'exact' comparison code is assumed.

Note: Filters may not apply to all fields.