Response

Here is a sample of the API response:

HTTP/1.1 200 OK
Date: Mon, 07 Sep 2015 23:02:09 GMT
Expires: Mon, 07 Sep 2015 23:02:09 +0000
ETag: "35676ce12ba0543c84489f3c393f5491"
Last-Modified: Mon, 07 Sep 2015 23:02:09 +0000
Content-Length: 245
X-API-Version: 1
Content-Type: application/json

{
    "status": 200,
    "data": {
        "id": 1,
        "name": "Test 1",
        "authentication_scheme": "NONE",
        "resource_type": "test",
        "resource_url": "https://brewfictus.kayako.com/api/v1/tests/1"
    },
    "resource": "test"
}

An API response has the status line, HTTP response headers (e.g., ETag) and often the body.

Status code

An API response as a HTTP response includes the HTTP status code that can have the following values:

Headers

The API service avoids using HTTP headers for delivering important information to API clients, except the Retry-After header that is described in Rate Limiting and the X-CSRF-Token header that is described in Security.

Body

The body of the API response is a special JSON object, that delivers meta data and resource information to the API client.

Main fields

Here are the most important fields of the response message:

Status

The value of this field is (normally) identical to the HTTP status code of the API response.

Data

This field delivers the main information. It contains either the resource or the collection (i.e. array of resources).

Resource

This field contains the type of the resource delivered in the data field. For collections it's the type of the contained resource.

Total Count

This field is returned only with collections and contains the total number of items in the collection.

Errors, notifications and logs

The response can include three types of special messages:

• Errors are intended for API clients (and, therefore, are not localized).
• Notifications are intended for end users (and are localized).
• Logs are to be logged by API clients and are intended for their developers and maintainers.

Errors

A response indicates an error, if its status is not 200 (OK) or 201 (Created) and the errors response field contains one or more error objects.

Some error objects can include the following additional fields:

Parameter

The `parameter` field holds the name of the parameter, that caused the error.

Parameters

If there are several parameters, that caused the error, they are listed in the `parameters` field.

Pointer

If the parameter is an array or a JSON object, the error object can additionally include the `pointer` field containing the exact path to the value in the parameter.

Example:

{
    "status": 400,
    "errors": [
        {
            "code": "RESOURCE_ACTION_NOT_AVAILABLE",
            "message": "Not supported method, misspelled action name or action is not available for the resource",
            "more_info": "https://developer.kayako.com/api/v1/reference/errors/RESOURCE_ACTION_NOT_AVAILABLE"
        }
    ]
}

See also Errors for what each error code means.

Notifications

Any response, successful or not, can include one or more notification objects in the notifications field.


The notification object contains the type field, that indicates the severity of the message.

The type can be:

• ERROR
• WARNING
• INFO
• SUCCESS

Additionally, the notification object can include the following fields:

Sticky

If the sticky field is set to true, the corresponding notification message should remain on the screen of the API client as reasonably long as possible.

Related URL

If the related_url field contains a URL, the API client may provide a UI element somewhere in the notification window, that would allow the user to check the resource represented by this URL. Or:

Related HREF

If the related_href field contains a URL, the API client should provide a UI element somewhere in the notification window, that would allow the user to open this URL in a browser.

Related label

If the related_label field is specified, its value should be used as a label for the aforementioned UI element.

Example:

{
    "status": 200,
    "notifications": [
        {
            "type": "INFO",
            "message": "A message has been sent to your email",
        }
    ]
}

Logs

Any response, successful or not, can include one or more log messages in the logs field.

The log object contains the level field, that indicates the severity of the problem.

The level can be:

• ERROR
• WARNING
• NOTICE

Example:

{
    "status": 200,
    "logs": [
        {
            "level": "NOTICE",
            "message": "To avoid long delays instead of supplying username and password with each request use just the session id"
        }
    ]
}