Response format and conventions
This page describes some common conventions we use in the API.
When a request succeeds, the format used in the response depends on the requested one. We strongly encourage you to use JSON, i.e. ask for
http://.../../<something>.json in your requests.
For instance, if you ask for
http://your-cartoque-server/servers.json, you'll get a list of your servers in json format.
Other formats are natively supported by the applications but should not be used within the API :
- html : it's for humans, hey!
- pdf : same here.
csv : only used for
/applicationsfor now, might disappear in the future ; NOT DOCUMENTED
- xml : same as csv, most likely to be removed in the next release since the world now has json :)
HTTP Response code
We'll use the same HTTP status code as everywhere. Here's a list of the subset we'll use, found in the great Stripe's API :
- 200 OK - Everything worked as expected.
- 400 Bad Request - Often missing a required parameter.
- 401 Unauthorized - No valid API key provided.
- 402 Request Failed - Parameters were valid but request failed.
- 404 Not Found - The requested item doesn't exist.
- 500, 502, 503, 504 Server errors - something went wrong on Cartoque's side.
About namespacing objects, we follow the same conventions as Gaug.es, documented here, if I quote John Nunemaker:
Again, we decided on a rule. In this case, all top level objects should be name-spaced, but objects referenced from a top level object or a collection of several objects did not require name-spacing.