Response Formats
Akahu returns API responses in a standard format, described here.
All Akahu API responses (and requests!) are JSON formatted, and should include a Content-Type: application/json
header.
We endeavour to keep a consistent style in our API responses.
{
"success": true,
"item_id": "user_ck9uh3kex000107muemzpdkr7"
}
{
"success": true,
"item": {
"_id": "user_ck9uh3kex000107muemzpdkr7",
"created_at": "2020-05-05T22:17:08.121Z",
"first_name": "Oliver",
"last_name": "Fawcett"
}
}
{
"success": true,
"items": [
{
"_id": "user_ck9uh3kex000107muemzpdkr7",
"created_at": "2020-05-05T22:17:08.121Z",
"first_name": "Oliver",
"last_name": "Fawcett"
}
]
}
{
"success": false,
"message": "Example error message"
}
All responses are contained in a wrapper object with the key success
present.
If success
is true
, you can expect your result to be found under the item_id
, item
or items
keys depending on whether the result is an ID, an item, or a list of items.
If success
is false
, you can expect a message
key with a description of what went wrong.
Akahu IDs
You may notice that some keys start with an underscore (like _id
above). This means that the value is an Akahu ID. Akahu IDs are composed of a prefix denoting the type of ID, and a suffix which is essentially random. For example user_ck9uh3kex000107muemzpdkr7
is a User ID.
Dates and Times
Akahu uses ISO 8601 date-time strings for all dates received or sent by the API. We accept timestamps in an any timezone, however all responses are returned in UTC.
Common Error Messages
Akahu uses the standard HTTP response codes set out here.
Below are some common error messages returned by the Akahu API. In addition to these, each endpoint may return more specific errors which are documented in our API Reference.
404 Not Found
This response indicates that the resource you have specified does not exist.
{
"message": "Not found"
}
401 Unauthorized
This response indicates that you do not have permission to view the specified resource. If you see this response, check to make sure you are sending the correct Authorization
header, and possibly X-Akahu-ID
header.
{
"message": "Unauthorized"
}
403 Forbidden
This response also indicates that you do not have permission to view the specified resource. If you see this response, check to make sure you are sending the correct Authorization
header, and possibly X-Akahu-ID
header.
{
"message": "Forbidden"
}
500 Internal Server Error
This response indicates that an error occurred in Akahu's systems.
{
"message": "Internal Error"
}
Updated over 1 year ago