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 (not implemented)message
is the error messagedetails
is the error detailmore_info
is the url to error documentation (not implemented)url
is the url that has responded with the error