Helpful Hints

Before we dive into the specifics of each data type, here are some helpful hints that will hopefully make it easier for you to work with the API.

Pretty-printing JSON

Most developers these days seem to prefer working with JSON-based data APIs for the simplicity that it offers over XML. The JSON that the Handshake API returns is compacted to save on transmission and processing time, however, this makes it hard to read by humans as the snippet below should make clear:

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

{"meta": {"limit": 500, "next": null, "offset": 0, "previous": null, "total_count": 40}, "objects": [{"billTo": {"city": "Birmingham", "country": "US", "fax": "555-555-5574", "id": 89, "phone": "123-456-7909", "postcode": "35243", "state": "AL", "street": "679 Rt. 6A", "street2": ""}, "cancelDate": null, "category": "NYTS", "ctime": "2010-12-28T20:07:01-05:00", "customer": {"contact": "Captain America", "email": "[email protected]", ...

Python has a great little JSON module that can be invoked from the command-line (even if you're not a Python programmer) that will pretty-print JSON for you and make it easier on your eyes:

$ curl https://app.handshake-app.com/api/v2/orders | python -mjson.tool

{
  "meta":{
    "limit":500,
    "next":null,
    "offset":0,
    "previous":null,
    "total_count":40
  },
  "objects":[
    {
      "billTo":{
        "city":"Birmingham",
        "country":"US",
        "fax":"555-555-5574",
        "id":89,
        "phone":"123-456-7909",
        "postcode":"35243",
        "state":"AL",
        "street":"679 Rt. 6A",
        "street2":""
      },
      "cancelDate":null,
      "category":"NYTS",
      "ctime":"2010-12-28T20:07:01-05:00",
      "customer":{
        "contact":"Captain America",
        "email":"[email protected]"
      },
      ...
    }
  ]
}

There is also a nice web-based JSON formatter tool by Curious Concept that can be used to make your JSON output easier to read.

Nice libraries and tools

As Python programmers, we were stuck with the lameness of urllib2 and httplib2 for years. They didn't make connecting to HTTP services much fun. Thank god for requests.