Partial Output

Many resources have many fields and nested resources, which in turn also have many fields and nested resources, and so on. This can make a response body huge.

To address this issue Kayako offers the following two solutions:

• Control, which types of resources will be included into the response.
• Control, which resource fields at which path will be included into the response.

By resource types

Kayako API service allows to specify, which types of resources should be included into the response. This can be controlled by the include argument, that should contain the comma-separated list of resource types.

The resource type is what is specified in the resource_type field of the resource, e.g, user, case.

The include argument

By default, the API service includes only references to nested resources, i.e., includes only id and resource_type fields of resources, e.g.:

"creator": {
    "id": 1,
    "resource_type": "user"
}

To include all nested resources (instead of just their references) set include to * (all types).

To include only certain types of resources, list these types in the include argument (separate by commas), e.g.:

?include=user,case

By resource fields

Kayako API service allows to control, which resource fields should be included into the response. This can be done by specifying field names in the fields argument.

Field categories

Resource fields in Kayako API fall into three categories:

• Fields, that are always returned (like id).
• Fields, that are returned by default.
• Fields, that are not returned by default.

There are also hidden fields, which are never returned (used only to set values - e.g. password).

The fields argument

To control, which fields should be returned in the response body, you can use the fields argument. In this argument you can specify the comma-separated list of field names, which can be prepended with optional modifiers.

Modifiers

The following modifiers are supported:

• + instructs to include the field name into the response
• - instructs to exclude the field name from the response

Example:

?fields=+full_name,-designation

Nested fields

To control fields of a nested resource specify corresponding rules in parentheses after the name of the field, that holds the nested resource, e.g.:

?fields=+role(+title,-type)

Certainly, to be able to control, which fields of nested resources should be included into the response, you must include these resources into the response by listing their types in the include argument.

Default display

The + modifier in display rules is actually optional and can be omitted, but this will change the default inclusion policy of the resource's fields.

Thus, if a field, that should be returned by default, is specified in display rules without the + modifier, all other default fields will no more be returned by default.

Thus:

• fields=title will return only id, and title.
• fields=+title will return id, title and other fields, that should be returned by default.
• fields=ip_restriction will return id, title, other default fields and the ip_restriction field.

Here title is a field, that is shown by default, and ip_restriction is a field, that is omitted by default.

Wildcard for all fields

You can also request to return all available fields of the resource by specifying * as the field name.

Examples: fields=*, fields=role(*)

This, however, won't affect fields of nested resources.

The special rule fields=*(*) can also be used to request all fields of all nested resources at any nesting level.