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