Resources

A resource is a data type that you access via one of our exposed API URLs. You can use the standard set of RESTful verbs (GET POST PUT DELETE) on each resource to fetch, create, update, and delete, respectively.

List vs. Detail Operations

As with most RESTful APIs, you can fetch / update multiple Handshake resources in a single call or work with one resource at a time.

The standard pattern for fetching a list of resources is:

# Fetch all the orders in the database
$ curl https://app.handshake-app.com/api/v2/orders

Fetch a specific resource by appending the resource's objID to the list URL:

# Fetch the order with order.objID == 89
$ curl https://app.handshake-app.com/api/v2/orders/89

When a GET response returns resource data, each resource has a resource_uri field indicating the specific URL where this resource can be retrieved / updated.

Supported HTTP Methods

• Unless specified otherwise, Handshake resources support GET POST on their list URLs and GET PUT DELETE on their detail URLs.
• Handshake resources do not support DELETE on their list URLs, because it would nuke your entire collection of that particular resource and we don't want to put this kind of nuclear firepower in your hands. If you really want to delete all instances of a particular resource type, you're going to have to do it one-by-one.
• Handshake resources do not support PUT on their list URLs, because the underlying behaviour would be to replace your entire collection of that resource with whatever you supply, which would potentially be highly destructive, and as mentioned above we do not want you throwing sticks of dynamite around like this. If you want to update a series of resources, you'll need to do the updates one-by-one.

Pagination

By default, lists of resources are returned in blocks of 100 records at a time. The meta dictionary that's returned tells you where you are up to, and if there's another page of results after this one, the next entry gives you the URL where it can be fetched.

$ curl https://app.handshake-app.com/api/v2/orders

{
  "meta":{
    "limit":100,
    "next":"/api/v2/orders?...", # URL for the next page of results 
    "offset":0,
    "previous":null,
    "total_count":860
  },
  "objects":[
    ...
  ]
}

Related Resources

A related resource is a resource that is connected to the resource in question. For example, a sales order is related to the customer it was written for through its customer property. Related resources are represented in the API in one of two ways.

Full mode

The complete data of the related resource is provided inline as a dictionary of values. This dictionary contains the same data that you would get if you fetched that related resource directly (including the resource_uri property as a key in the dictionary).

Below is a trimmed down example of a customer resource with the bill-to address in full mode:

{
   "billTo":{
      "btCustomer":"/api/v2/customers/43",
      "city":"Brooklyn",
      "country":"US",
      "fax":"555-555-5559",
      "objID":44,
      "phone":"123-456-7894",
      "postcode":"11217",
      "resource_uri":"/api/v2/addresses/44",
      "stCustomer":null,
      "state":"NY",
      "street":"8051 Brown Road",
      "street2":""
   },
   "contact":"Kelly Slater",
   "email":"[email protected]",
   "entityType":"Customer",
   "id":"C1004",
   "name":"The Globe",
   ...
}

Reference mode

The resource_uri of the related resource is given as a string. The same customer as above is given below with the bill-to address in reference mode:

{
   "billTo":"/api/v2/addresses/44",
   "contact":"Kelly Slater",
   "email":"[email protected]",
   "entityType":"Customer",
   "id":"C1004",
   "name":"The Globe",
   ...
}

We tend to use reference mode when returning data for GET requests, however we will use full mode for relationships where it makes sense to provide more complete info (e.g. when fetching sales orders, we assume you will usually want to see the data for the customer attached to that order). This saves an extra GET to our API to collect all the other stuff you want to know about.

Best practices for related resources

When writing to the API via a POST or PUT, you can specify related resources in either format, but some recommended strategies for working with relationships are:

• If you're updating an existing resource via PUT, unless you really mean to make changes to the resource's related objects, you should specify the relationships in reference mode, or if you don't want to change the relationships, just leave them out altogether. This guarantees you aren't going to accidentally write changes to the related resources when you're really just trying to update the parent resource.

• If you're creating a new resource via POST with relationships to existing resources (for example, creating a new customer that is related to an existing customer group), use reference mode to avoid accidentally creating new, duplicate versions of those related resources.

• If you're creating a new resource via POST with relationships to new sub-resources (for example, creating a new customer with a list of new ship-to addresses), then you should specify those related resources in full mode so that you can create them all together in a single request.

Disabling full mode

Sometimes, you might prefer to fetch resources with all relationships in reference mode for efficiency's sake. To turn off full mode for a single request, simply pass full=false as part of your query string, e.g.:

# Fetch orders with all relationships in reference mode
$ curl https://app.handshake-app.com/api/v2/orders?full=false

Filtering

You can filter out the results that are returned to you by the server by passing filter names in your query string. The specific filters that are supported for each data type are detailed in the API documentation for that type.

As an example, orders can be filtered by their category as follows:

# Fetch orders as XML in the category with ID 'NYTS'
$ curl https://app.handshake-app.com/api/v2/orders.xml?category=NYTS

When passing filter parameters in URLs you need to percent-encode them. Spaces need to be replaced with %20. Your HTTP library might do this automatically, but you should be aware of it.

# Fetch orders as XML in the category with ID 'NYTS 2011'
$ curl https://app.handshake-app.com/api/v2/orders.xml?category=NYTS%202011

Common Filters

The filters below apply to all resources, and can be used on any GET request to restrict the set of results that will be returned.

ctime (datetime)

Filters by the resource's creation time with a comparison operator, which should be one of:

• gt (greater than)
• gte (greater than or equal)
• lt (less than)
• lte (less than or equal)

For example:

# Fetch orders created after 2011-10-12 10:39:04pm UTC
$ curl https://app.handshake-app.com/api/v2/orders?ctime__gte=2011-10-12T22:39:04Z

mtime (datetime)

Filters by the resource's last-modified time using the same operators as ctime above.

Ordering

You order the results that the API returns by passing the order_by parameter in your query string. By default, orderings are ascending, but the ordering key can be prefixed with a minus to request a descending sort.

For example, to fetch resources by their creation time:

# Fetch orders by date created, ascending
$ curl https://app.handshake-app.com/api/v2/orders?order_by=ctime

# Fetch orders by date created, descending
$ curl https://app.handshake-app.com/api/v2/orders?order_by=-ctime

All resources support at least the following three orderings:

• objID: results are ordered by their object ID
• ctime: results are ordered by their date created
• mtime: results are ordered by their date modified

Common Fields

The fields and methods below are available for all Handshake resources.

object.objID (readonly integer)

A positive integer that uniquely identifies this resource within your account. This integer forms the last part of the resource_uri for each resource.

This is not guaranteed to be globally unique and it is possible that this ID might be repeated in another Handshake account. If you only administer a single Handshake account you can treat this as globally unique.

object.uuid (readonly UUID)

A UUID4 that uniquely identifies this resource and is guaranteed to be globally unique.

object.ctime (readonly datetime)

The time at which this resource was first created. If this resource was created directly on the server (e.g. during an import) then this value will be exactly correct. If this resource was created on a iOS device, then it may be off by a small amount, usually fractions of a second.

object.cdate (readonly date)

The date part of the ctime without the time part.

object.mtime (readonly datetime)

The time at which this resource was last modified. It is subject to the same accuracy guarantees as ctime above.

object.owner (readonly reference to User)

The User who originally created this resource.