API (v1.1)

Responses

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.

Specifying an output format

To specify an output format, when available, you just need to append it to the endpoint name, like so:

$ curl -u api_key: https://www.vendus.es/ws/v1.1/account.xml
$ curl -u api_key: https://www.vendus.es/ws/v1.1/account/23423.xml

JSON Responses

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
    }
]

HTTP Status Codes

We use HTTP status codes to indicate success or failure of a request.

Success Codes

• 200 OK - Request succeeded. Response included
• 201 Created - Resource created. URL to new resource in Location header
• 204 No Content - Request succeeded, but no response body

Error Codes

• 400 Bad Request - Could not parse request
• 401 Unauthorized - No authentication credentials provided or authentication failed
• 403 Forbidden - Authenticated user does not have access
• 404 Not Found - Resource not found
• 415 Unsupported Media Type - POST/PUT/PATCH request occurred without a valid content-type header
• 422 Unprocessable Entry - A request to modify or create a resource failed due to a validation error
• 429 Too Many Requests - Request rejected due to rate limiting
• 500, 501, 502, 503, etc - An internal server error occured

Enveloping

If 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"
  }
}