This section describes the structure of our API responses
Responses from the API are always returned with the application/json content type.
We'll separate responses into standard and error responses which will be described below.
Standard Responses
Standard responses always come back with a 2XX response status and most of them, save a few, have this general structure
{
"data": Object|Array,
"meta": Object (Optional)
}
Standard responses can be equally broken down into 3 groups, they are:
- Item responses
- Collection responses
- Informational responses
- Error responses
Item Responses
An item resource will always be returned when you call an endpoint that returns a distinct resource from the service; for instance, creating a resource or viewing a resource.
{
"data": {
"embeds": [
"customer",
"added_by_user"
],
"id": "tag_JZYCnWZcMFeNroIW8GbfB",
"tag": "utilities",
"description": null,
"is_trashed": false,
"deleted_at": null,
"created_at": "2020-06-11T10:07:00+01:00",
"updated_at": "2020-06-11T10:07:00+01:00"
}
}
Collection Responses
A collection response will always be returned when you call an endpoint that returns many items of the same resource type; for instance, when you're listing resources.
One attribute of collection endpoints is that they might support pagination.
Supports the "include" query parameter
Since a collection is a set of items, it also supports explicitly including relationships. When you specify the relationships to include, it is applied across all the items in the collection.
{
"data": [
{
"embeds": [
"customer",
"added_by_user"
],
"id": "tag_3pwlvaDlcdlGcLkghLEVrh",
"tag": "bills",
"description": null,
"is_trashed": false,
"deleted_at": null,
"created_at": "2020-06-25T09:24:49+01:00",
"updated_at": "2020-06-25T09:24:49+01:00"
},
{
"embeds": [
"customer",
"added_by_user"
],
"id": "tag_7VDNquaDGKeEeiIB4wwToJ",
"tag": "deliverables",
"description": null,
"is_trashed": false,
"deleted_at": null,
"created_at": "2020-06-11T11:07:17+01:00",
"updated_at": "2020-06-11T11:07:17+01:00"
},
{
"embeds": [
"customer",
"added_by_user"
],
"id": "tag_JZYCnWZcMFeNroIW8GbfB",
"tag": "utilties",
"description": "Mostly for payment items to mark utilities",
"is_trashed": false,
"deleted_at": null,
"created_at": "2020-06-11T10:07:00+01:00",
"updated_at": "2020-06-11T10:48:44+01:00"
}
]
}
Informational Responses
Informational responses are returned from the API when the endpoint doesn't return a distinct item or collection of items. This occurs in various situations:
- Authentication
- Deletion operations
One common property of these responses is that they're not enclosed in a data key.
{
"message": "Successfully deleted the tag"
}
Error Responses
When things go wrong, the API is able to provide feedback on what went wrong and it also regurgitates what was sent to in come cases.
{
"error": {
"status": 422,
"title": "Error",
"description": "Some data failed validation in the request",
"source": {
"otp": [
"The otp field is required."
]
}
}
}
{
"error": {
"status": 404,
"title": null,
"description": "Could not find the attachment",
"source": {
"path": "/attachments/pay_11zYeXXUKBSe2FvXEvG2NI",
"method": "GET"
}
}
}
{
"error": {
"status": 409,
"title": "Account exists",
"description": "An account already exists for the email [email protected]",
"source": {
"country": "NG",
"customer": {
"name": "Ciroma Inc."
},
"user": {
"firstname": "Adamson Ciroma",
"email": "[email protected]",
"password": "admin",
"phone": "09098112345"
},
"auto_login": 1,
"path": "/auth/register",
"method": "POST"
}
}
}