Responses¶
In HiveApi you can define your own response payload or use one of the supported serializers. Currently the supported
serializers are (ArraySerializer
, DataArraySerializer
and JsonApiSerializer
) provided by
Fractal.
By default HiveApi uses DataArraySerializer
. Below is an example of the response payload.
{
"data": [
{
"id": 100,
...
"relation 1": {
"data": [ // multiple items
{
"id": 11,
...
}
]
},
"relation 2": {
"data": { // single item
"id": 22,
...
}
}
}
},
...
],
"meta": {
"pagination": {
"total": 999,
"count": 999,
"per_page": 999,
"current_page": 999,
"total_pages": 999,
"links": {
"next": "http://api.hive.local/v1/accounts?page=999"
}
}
},
"include": [ // the other resources that may be included dynamically on request
"xxx",
"yyy"
],
"custom": []
}
Paginated Response:¶
When the returned data is paginated the response payload will contain a meta
description with information about the
pagination.
{
"meta": {
"pagination": {
"total": 999,
"count": 999,
"per_page": 999,
"current_page": 999,
"total_pages": 999,
"links": {
"next": "http://api.hive.local/v1/accounts?page=999"
}
}
},
"include": [ // what can be included
"xxx",
"yyy"
],
"custom": []
}
Including Resources¶
The include
field in the response informs the client about relationships that can be include on request. The client,
in turn, may tell the server by adding additional query parameter, for example /users?include=roles
For more details read the Relationships
section in the Query Parameters page.
Change the default Response payload:¶
By default, HiveApi returns the data by applying the DataArray
Fractal Serializer (League\Fractal\Serializer\DataArraySerializer
).
To change this behaviour, you can adapt your .env
file accordingly:
API_RESPONSE_SERIALIZER=League\Fractal\Serializer\DataArraySerializer
Currently, the supported Serializers are
ArraySerializer
DataArraySerializer
JsonApiSerializer
More details can be found at the Fractal website and Laravel Fractal Wrapper.
In case of returning JSON data (JsonApiSerializer
), you may also want to check some JSON response standards:
Resource Keys¶
JsonApiSerializer¶
The selected serializer allows appending a ResourceKey
to the transformed resource. You can set the ResourceKey
in
your response payload in 2 ways:
- Manually set it via the respective parameter in the
$this->transform()
call. Note that this will only set thetop level
resource key and does not affect the resource keys fromincluded
resources! - Specify it on the respective
Model
by overriding the$resourceKey
(protected $resourceKey = 'FooBar';
). If no$resourceKey
is defined atModel
level, the lower-cased, pluralizedShortClassName
is used as key. For example, theShortClassName
ofApp\Containers\User\Models\User::class
is simplyUser
. The resulting$resourceKey
, therefore, isusers
.
DataArraySerializer¶
By default the object
keyword is used as a resource key for each response, and is manually defined in each transformer,
Error Responses Formats¶
Visit each feature, example the Authentication and there you will see how an unauthenticated response looks like, same for Authorization, Validation and so on.
Building a Responses from the Controller¶
Checkout the Controller Response Builder Helper functions for more information on this topic.