General Notes

Format

Content can be sent and received from the API using JSON and XML. To specify a particular response format append ".json" or ".xml" to the url, although json is the default format and so doesn't actually require the ".json" extension. Furthermore, please remember to set the header value for "Content-Type" to either "application/json" or "application/xml".

Versioning

The URL's given in the various API's (eg. /api/v1/suppliers) point to a specific version. The latest version is always accessible by omitting the version designation, eg. /api/suppliers. This applies to all of the URLs given so feel free to use it or not depending on your concern around about potentially "code-breaking" changes. However, we will make every effort possible to ensure smooth rollovers with plenty of warning should such changes become necessary.

We will reserve the right to include additional fields when viewing resources on a given version number, so if it becomes important to including an extra field (say, a summary field), we may add the field without changing the version. In other words, please don't assume that the list of "read fields" will never grow, although we do commit to never changing the name for a given field in a version.

Testing

Testing (or dry-runs) can be done at any time by including "?test=true" in the requested URL. If this is present, then no actual resources will be created, updated or deleted but the effect will be simulated and it will behave as if the update was real (although this applies only to the specific request). It will be against live data though, so viewing resources will actually reflect the real data.

Authentication

We use digest authentication which can be a little tricky to setup but our authentication guide should resolve any questions that you have with it.

Heartbeats

There is an action exposed on each resource called the Heart Beat. Calling it will allow you to test that authentication is working and that the API is still functioning as it ought to. Calling it will return the account name as well as a 200 status code. More details are given in each resource's API.