Response and Errors¶
Response¶
Usually the response of API query has the structure
{
"api": "objects",
"data": {},
"method": "get",
"params": [],
"url": "https://example.com/api/v1/objects/1"
}
where:
api
is the endpoint calleddata
is an object containing all data requestedmethod
is the HTTP verb used in the requestparams
contains all query url params used in the requesturl
is the complete url requested (full base url + basepath + endpoint + other)
To set data
for response is available the method
ApiBaseController::setData()
that accepts an array as first
argument. A second argument permits to replace (default) or merge
present data with that passed.
Other meta data can be placed inside response object, for example
paging
useful to paginate results:
{
"api": "objects",
"data": {},
"method": "get",
"paging": {
"page": 1,
"page_size": 10,
"page_count": 10,
"total": 995,
"total_pages": 100
},
"params": [],
"url": "https://example.com/api/v1/objects/1/children"
}
where:
page
is the current pagepage_size
is the page dimensionpage_count
is the number of items inside current pagetotal
if the count of all itemstotal_pages
is the total pages available
Note
If you need to serve empty response body to client you can use
ApiBaseController::emptyResponse()
that by default send a 204 No
Content HTTP status code. Pass another status code as first argument to send
different status code.
Errors¶
Every time the API thrown an error the response will be similar to
{
"error": {
"status": 405,
"code": null,
"message": "Method Not Allowed",
"details": "Method Not Allowed",
"more_info": null,
"url": "https://example.com/api/v1/foobar"
}
}
where:
status
is the HTTP status codecode
is the API error code (if exists)message
is the error messagedetails
is the error detailmore_info
can contain useful information for better understand the error.url
is the url that has responded with the error
Error codes¶
Here is a list of the error codes thrown from the API.
Error Code | Description | HTTP status code |
---|---|---|
UPLOAD_MAX_FILESIZE_EXCEEDED | Upload max file size exceeded | 400 Bad Request |
UPLOAD_QUOTA_EXCEEDED | Upload quota available exceeded | 403 Forbidden |
UPLOAD_FILES_LIMIT_EXCEEDED | Maximum number of files allowed exceeded | 403 Forbidden |