Request

Here is a sample of the API request:

POST /api/v1/tests?_empty=false HTTP/1.1
Host: brewfictus.kayako.com
Accept: */*
Content-Length: 43
Content-Type: application/x-www-form-urlencoded

name=Caryn+Pryor&array_items=1,2,3&is_boolean=true

A valid API request has the request line with optional arguments (e.g. _empty), HTTP request headers (e.g. Content-Type) and sometimes the body, that usually contains parameters (e.g. is_boolean).

Headers

Here are some of HTTP headers that can/should be used in the requests:

Other request headers are reviewed in Authentication, File Upload, Caching, Security, Special Options and Using JavaScript.

Accept

The Accept HTTP header must include application/json or */*.

Accept: application/json

Content-Length

Be sure to specify the size of the request body in the Content-Length HTTP header:

Content-Length: 53

Content-Type

Depending on the format of the request body the Content-Type HTTP header must be set to:

• application/x-www-form-urlencoded for the URL-encoded format.
• application/json for the JSON format.
• multipart/form-data with the boundary for the Multi-part format.

Content-Type: application/x-www-form-urlencoded

Arguments and parameters

We distinguish parameters, that are specified in the request URL (query), which we name "arguments", and parameters, that are specified in the request body, which we name just "parameters".

"Arguments" and "parameters" can be combined in a single API request (therefore, in theory, they can even have the same names).

Some special arguments are reviewed in Partial Output, Pagination, File Upload, Special Options and Using JavaScript.

Body format

Body of a valid API request must be in one of the following formats:

URL-encoded

This is a standard format of web forms and the simplest one.

This format is identified by the application/x-www-form-urlencoded value of the Content-Type HTTP request header:

Content-Type: application/x-www-form-urlencoded

In this format the body of the request must contain a single (long) line with name=value pairs of parameters joined by &. Values must be URL-encoded.

Example:

name=Caryn+Pryor&integer_number=123&float_number=1.5&&date=1441118415&is_boolean=1&array_items[]=1&array_items[]=2

For details about this format check RFC 3986.

CURL

Example of the CURL command, that uses this format:

curl -X POST \
     -d 'name=Caryn Pryor' \
     -d integer_number=123 \
     -d float_number=1.5 \
     -d date=1441118415 \
     -d array_items[]=1 -d array_items[]=2
     -d is_boolean=true 'https://brewfictus.kayako.com/api/v1/tests&_empty=false'

JSON

JSON is a standard format for APIs nowadays and the most flexible one. It is also used by the Kayako API as the response format.

For a JSON request the Content-Type HTTP request header must be set to application/json:

Content-Type: application/json

The body of the request must contain a valid JSON object.

Example:

{
    "name": "Caryn Pryor",
    "integer_number": 123,
    "float_number": 1.5,
    "date": "2015-09-01T14:45:04+05:00",
    "is_boolean": true,
    "array_items": [1, 2]
}

You can read more about JSON here.

CURL

Example of the CURL command, that uses this format:

curl -X POST \
     -H 'Content-Type: application/json' \
     -d '{"name": "Caryn Pryor",
          "integer_number": 123,
          "float_number": 1.5,
          "date": "2015-09-01T14:45:04+05:00",
          "is_boolean": true,
          "array_items": [1, 2]
         }' 'https://brewfictus.kayako.com/api/index.php?/v1/tests&_empty=false'

Multi-part

This is another standard format of web forms and the only one, that can be used to upload files. It's also the most complicated one.

This format is identified by the Content-Type HTTP request header, that must be set to multipart/form-data and also must include the boundary:

Content-Type: multipart/form-data; boundary="1modcYGLAATJpapo8jhD4UwHbF5asu4u"

As this is one of the request formats, that can be used to upload files, it is also described in details in File upload.

If this format is used to deliver values for parameters, the corresponding "part" must include the parameter name in the name option of the Content-Disposition HTTP header as follows:

Content-Disposition: form-data; name="parameter_name"

The request body of this format must contain one or more parts separated by the boundary.

Example:

--1modcYGLAATJpapo8jhD4UwHbF5asu4u
Content-Disposition: form-data; name="name"

Caryn Pryor
--1modcYGLAATJpapo8jhD4UwHbF5asu4u
Content-Disposition: form-data; name="integer_number"

123
--1modcYGLAATJpapo8jhD4UwHbF5asu4u
Content-Disposition: form-data; name="float_number"

1.5
--1modcYGLAATJpapo8jhD4UwHbF5asu4u
Content-Disposition: form-data; name="date"

2015-09-01T14:45:04Z
--1modcYGLAATJpapo8jhD4UwHbF5asu4u
Content-Disposition: form-data; name="is_boolean"

1
--1modcYGLAATJpapo8jhD4UwHbF5asu4u
Content-Disposition: form-data; name="array_items[]"

1
--1modcYGLAATJpapo8jhD4UwHbF5asu4u
Content-Disposition: form-data; name="array_items[]"

2
--1modcYGLAATJpapo8jhD4UwHbF5asu4u--

Check also RFC 2388 for more details about this format.

CURL

Example of the CURL command, that uses this format:

curl -X POST \
     -F 'name=Caryn Pryor' \
     -F integer_number=123 \
     -F float_number=1.5 \
     -F date=1441118415 \
     -F array_items[]=1 -F array_items[]=2
     -F is_boolean=true 'https://brewfictus.kayako.com/api/v1/tests&_empty=false'

File upload

For request formats, that can be used to upload files, check File upload.