Ruby API Library

Officially Maintained API Library This API library is open-source and officially maintained by Kayako.

Prerequisites

Kayako

To use Kayako REST API, first you need to enable it in your Kayako installation. To enable the API, login to Admin Control Panel and in Options panel on the right choose REST API, and then Settings. Next, set Enable API Interface to Yes and confirm the change by clicking Update button.

Ruby

The Ruby API client requires version 1.8 or later of Ruby. For better performance it is recommended to install HTTPClient and LibXML libraries. The Ruby API client tries to load these libraries and falls back to Ruby's core Net::HTTP and REXML in case of failure.

Getting Started

Before you can start using the Ruby Kayako REST API client you need to load kayako_client by adding the following line to your Ruby code:

Configuring the client

To perform network operations the Ruby REST API client requires API URL, API Key and Secret Key. You can obtain their values in Admin Control Panel - in Options panel on the right choose REST API and then API Information. Specify obtained values in the global configuration of the library:

Basic concepts

The Ruby REST API client was designed to be as close to the Kayako REST API specification as possible making its usage very intuitive. Thus the library's classes were named after the REST API objects:

• KayakoClient::CustomField
• KayakoClient::Department
• KayakoClient::Staff
• KayakoClient::StaffGroup
• KayakoClient::Ticket
• KayakoClient::TicketAttachment
• KayakoClient::TicketCount
• KayakoClient::TicketCustomField
• KayakoClient::TicketNote
• KayakoClient::TicketPost
• KayakoClient::TicketPriority
• KayakoClient::TicketStatus
• KayakoClient::TicketTimeTrack
• KayakoClient::TicketType
• KayakoClient::User
• KayakoClient::UserGroup
• KayakoClient::UserOrganization

Except TicketSearch which is available as :search method of the KayakoClient::Ticket class.

The main class and instance methods are also named after the REST API methods:

• :get for GET method
• :put for PUT method
• :post for POST method
• :delete for DELETE method

Special method :all is used to retrieve all objects (a.k.a. ListAll).

For user convenience special Rails-style aliases were added:

• :find for :get
• :update for :put
• :save for :post
• :destroy for :delete

Ruby method aliases are widely used by the library to improve comprehension and preserve similarity with the REST API. For example, REST object properties setter and getter methods in the library have underscores (e.g. :creator_staff_name) while REST XML properties do not contain ones. The library provides setter and getter method aliases identical to the names used in REST XML (e.g. :creatorstaffname).

Usage scenarios

All classes are used in very much the same way.

Getting all objects

The Class#all method always returns array of class instances:

Getting an object

The Class#get method returns a class intance or nil:

Creating an object

An instance of a class is created as usual:

Object properies can be changed using setter methods:

Upload is done using Object#post method which returns true on success and false on failure:

As an alternative you can use Class#post which returns either a class instance or nil:

Modifying an object

To change object properties use setter methods:

Then use Object#put to update. The Object#put method returns either true (on success) or false:

Deleting an object

To delete an object use Object#delete method:

As an alternative you can use Class#delete method which requires object ID:

Advanced Topics

Hash-like accessors

In addition to setter and getter methods described above the library also support Hash-like accessors:

Similar accessor is also available for KayakoClient::TicketCustomField instances:

Setting custom fields

At the moment the only way to set custom fields is to use POST. In the POST request you need to specify all values for all custom fields.

Check the sample code:

You can also set values without fetching current ones:

The full list of available custom fields can be fetched this way:

File uploads

The Ruby REST API library supports file uploads/downloads for KayakoClient::TicketAttachment and KayakoClient::TicketCustomFieldValue (only download) objects.

To upload a file as an attachment you can do:

The :file accessor accepts a path to file (String) or a File/Tempfile instance:

The :file accessor can also be used to access a downloaded file:

The Tempfile instance is created on first call to the :file accessor.

Associated object

For user convenience the Ruby REST API library also provides instance methods for getting associated object. Thus most of objects having a property :<something>_id also have a method :<something>. When such method is called the library transparently fetches and returns the corresponding object.

The associated object is received only once and gets cached.

Specifying HTTP backend

Currently the Ruby REST API library supports HTTPClient and Net::HTTP. By default it tries to load HTTPClient and switches to Net::HTTP if failed. But it's possible to specify HTTP backend explicitly:

Or:

You can also pass the instance of KayakoClient::NetHTTP class as a HTTP backend:

Specifying XML backend

Currently the Ruby REST API library supports LibXML and REXML::Document. By default it tries to load LibXML and switches to REXML::Document if failed. But it's possible to specify XML backend explicitly:

Client instance

Instead of specifying global configuration you can configure a client instance and then use it to access Kayako, e.g.:

The full list of client instance methods can be found below.

Debuggin/logging

To enable logging you need to pass a Logger object as follows:

Under Rails you can use Rails.logger:

Error Handling

The following exceptions can be raised when an error occurs:

The ArgumentError is raised when e.g. required properties where not supplied. In cases when a value is invalid (not an allowed value etc) nothing is raised. Instead the corresponding method (:put or :post) returns false. In this case the errors can be fetched by calling to :errors method:

For this reason it is recommended to always use Object#post instead of Class#post.

Usage Examples

It is assumed that the REST API client has been configured properly as described above.

Creating a department

Creating a staff user

Creating a user

Creating a ticket and adding a ticket note

Performing a ticket search

Supported Methods

API Complete This library supports all of the presently available [DEV:REST API] methods.