Responses

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