About the API¶
A few things you must know before diving into the API:
Everything is JSON¶
Every request should have a JSON payload; anything else will be refused and return a 400 status. For example:
POST /randomendpoint
Host: example.com
Accept: text/html
Content-Type: application/x-www-form-urlencoded
field1=value&field2=value
The response will always be:
HTTP/1.1 400 Bad Request
Content-Type: application/json
{ "status": "ERROR", "message": "Request MUST be in JSON format" }
If instead you do a proper JSON request with:
POST /randomendpoint
Host: example.com
Content-type: application/json
{ "field1": "value", "field2": "value" }
Then everything would go fine.
Standard responses¶
Responses will always have a status parameter with the result of the operation – more fields may be also returned, depending on the request.
Successful requests with have the value OK for status – and, again, more fields may be returned in most cases. Also, the HTTP status code will always be 200.
In case of failure, status will have the text ERROR (in all caps) and a message field will have the reason for the error – and, as success, it may contain more fields with information about the error. For different errors in the operation there will be a different HTTP status. We tried as hard as possible to give each error a meaningful HTTP status, even if this sometimes wouldn’t make much sense – for example, if you try to change the ownership of a group and the group doesn’t exist, you’ll get a 404 status; if the new owner doesn’t exist, instead of a proper 404, we will return a 412 status, not because there is a precondition error in the headers, but because we need a different code to point that the new user does not exist.
Redirects¶
All URLs must end with “/”; if you forget to add them in the URL, you’ll receive a redirect to the path with “/”.