By default, all responses are JSON encoded. However, depending on the endpoint your are using, other output formats might be available, like XML, CSV, PDF or even others.
To specify an output format, when available, you just need to append it to the endpoint name, like so:
$ curl -u api_key: https://pos.cloudware.pt/ws/v1.1/account.xml
$ curl -u api_key: https://pos.cloudware.pt/ws/v1.1/account/23423.xml
As stated above, the default for responses is JSON.
A single resource is represented as a JSON object:
{
"id": 123,
"title": "My Title",
"price": 243.56
}
A collection of resources is represented as a JSON array of objects:
[
{
"id": 123,
"title": "My Title",
"price": 243.56
},
{
"id": 124,
"title": "My New Title",
"price": 271.12
}
]
We use HTTP status codes to indicate success or failure of a request.
Success Codes
200 OK
- Request succeeded. Response included201 Created
- Resource created. URL to new resource in Location header204 No Content
- Request succeeded, but no response bodyError Codes
400 Bad Request
- Could not parse request401 Unauthorized
- No authentication credentials provided or authentication failed403 Forbidden
- Authenticated user does not have access404 Not Found
- Resource not found415 Unsupported Media Type
- POST/PUT/PATCH request occurred without a valid content-type header422 Unprocessable Entry
- A request to modify or create a resource failed due to a validation error429 Too Many Requests
- Request rejected due to rate limiting500, 501, 502, 503, etc
- An internal server error occuredIf your HTTP client makes it difficult to read status codes or headers, we can package everything neatly into the response body.
Just include envelope=true
as a request parameter and the API will always return a 200 HTTP status code. The real status, headers and response will be within the body.
GET /api/v1/users/does-not-exist?envelope=true
200 OK
{
"status": 404,
"headers": {
"Rate-Limit-Limit": 100,
"Rate-Limit-Remaining": 50,
"Rate-Limit-Used": 0,
"Rate-Limit-Reset": 25
},
"response": {
"message": "Not Found"
}
}