Conventions
Data Formats
Resources can be represented as either JSON or XML. JSON is the default, but you can specify the format by appending ".json" or ".xml" to the URL.
https://app.handshake-app.com/api/v2/orders
https://app.handshake-app.com/api/v2/orders.json
https://app.handshake-app.com/api/v2/orders.xml
When doing a POST or PUT to the API with your own data in the request body, you must supply the Content-Type header on your request that specifies the type of data you are uploading:
- JSON requests should use
application/json - XML requests should use
application/xml
API Versioning
While we make every effort possible to minimize changes to the API so that we don't break your existing integrations, it's possible that over time there might be necessary changes. When this happens, we will continue to support the old and new versions of the API in parallel for a period of time to give you time to test your existing code against the new API. If you're lucky, everything will work magically, but otherwise you'll have plenty of time to migrate.
When a request is made to the API, it must include the API version in the URL. The standard format for an API request URL is /api/<versionNumber>/<resourceName>.
The API is at version 2, so request URLs should look like:
https://app.handshake-app.com/api/v2/<resourceName>
We may add to the API at any time
We reserve the right to make additions to the API without notification or altering the base version number of the API. This means we will not alter the behaviour of existing fields without warning, but will add new fields and / or resources to support new functionality as it is implemented elsewhere in Handshake.
From a practical perspective, this simply means that you should not build integrations that assume that the set of available fields will not grow (although you can of course build an integration that assumes that the set of available fields will not shrink).
Rate Limiting / Throttling
We allow you to make up to 60 requests to our API in a one-minute period. This should allow you enough bandwidth to perform integrations without placing an unnecessarily large burden on the Handshake servers.
If you exceed this limit, your requests will be denied with a 429 (TOO MANY REQUESTS) response until the one minute window elapses and you are allowed to make requests again.
If you exceed this limit by a huge margin (i.e. our system detects that you are abusing the API), your access to the API may be revoked. We encourage you to correctly handle a 429 response code to avoid your integration being flagged for abuse.
Field Name & Type Notation
Throughout this documentation, the data type of each field is indicated next to the name, a la:
object.fieldName (<datatype>)
Most fields have a description following their signature, however, where the meaning is sufficiently obvious, only the name and type of the field will be given.
Some fields are marked as readonly meaning that they are provided for your information but writing to them via a POST or PUT request will have no effect.
Some fields are marked as server-only meaning that they only exist on the website, but are not available on the iOS apps, and so should not be used in templates that need to work on iPads or iPhones.
Date / Time Formatting
The API returns dates in ISO-8601 format. This means they are formatted as YYYY-MM-DDTHH:MM:SSZ where:
- the
Tin the middle is just a separator between the date and time. - the
Zat the end is the timezone specifier for UTC.
For example, November 8th, 2010, at 5:47:40pm in New York (which is 10:47:40pm UTC since New York is UTC -5:00) would be represented as 2010-11-08T22:47:40Z.
Unicode data
All unicode data returned by the Handshake API is encoded as UTF-8. When the response is in XML format, this is explicitly indicated in the header:
<?xml version='1.0' encoding='utf-8'?>
JSON format responses also use a UTF-8 encoding, even though that fact is not explicitly stated in the response.
When pushing data into Handshake, you should (obviously) also use a UTF-8 encoding for all unicode data.