Tiktrac API

NOTE: This API is currently discontinued in favour of the REST API

Overview

The Tiktrac API can be accessed with XMLRPC and provides access to several of Tiktrac’s core features.

You can:

The URL

The URL used to access the API is:

http://youraccount.tiktrac.com/api/tiktrac/

Where ‘youraccount’ is the subdomain you use to access Tiktrac.

Authentication

When any call is made to the API, your email address and API token must be sent as the first two parameters. This authenticates you with the API.

Your API token

API tokens can be generated from within the Tiktrac web interface. Under Your Settings, there is a section called Manage your API token.

It is important to note that almost anything you can do in Tiktrac, the API can do too. Therefore, ensure that your API token is known only to you. If you feel that your API token may have become compromised, you can regenerate a new one.

Code examples

I know everyone will just skip ahead and read this first, so before getting bogged down with the method and data structure reference, here’s some code.

Ruby

require 'xmlrpc/client'
server = XMLRPC::Client.new2('http://helicoid.tiktrac.com/api/tiktrac/')
result = server.call2('getMyTasks', 'alex@alexyoung.org', 'Y1zdWJ')

This uses the xmlrpc library (1) to open a connection to Tiktrac (2) and then request all my tasks (3).

PHP

Java

Data structures

There are three main data structures returned by the API: ClientStruct, SheetStruct and TaskStruct. These form a hierarchy: a task has a sheet and a sheet has a client.

ClientStruct

SheetStruct

TaskStruct

API methods

All calls to the API contain email and token. These are both strings.

Clients

getClients(email, token)

Returns all the clients you can access as an array of ClientStructs.

getClient(email, token, id)

Returns a client (ClientStruct) with the id provided.

newClient(email, token, name, cost)

Create a client, with:

Returns a boolean.

updateClient(email, token, id, name, cost)

Update a client’s parameters. Note that all parameters must be supplied, or the parameter will be overwritten with empty strings.

Returns a boolean.

destroyClient(email, token, id)

Delete the client with the supplied id. This is not recoverable.

Returns a boolean.

Sheets

getSheets(email, token)

Returns the list of sheets (SheetStructs) that you can access.

getSheet(email, token, id)

Returns a SheetStruct with the supplied id.

newSheet(email, token, name, description, client_id, time_format, total_time)

Create a sheet, with the following parameters:

Returns a boolean.

updateSheet(email, token, id, name, description, time_format, total_time)

Update a sheet with the supplied parameters. All parameters must be provided, so if you want to keep the values the same, use getSheet to find out the currently set parameters.

Returns a boolean.

destroySheet(email, token, id)

Deletes the sheet with the supplied id. This is not recoverable.

Returns a boolean.

Tasks

getMyTasks(email, token)

Returns a list of tasks (TaskStructs) you have posted.

getTasksForSheet(email, token, sheet_id)

Returns tasks (TaskStructs) for a particular sheet. You can find out the sheet’s id by using getSheets and searching for it.

getTask(email, token, id)

Returns the task with id as a TaskStruct.

completeTask(email, token, id)

Set a task with id to ‘completed’.

Returns a boolean.

openTask(email, token, id)

Set a task with id to ‘open’.

Returns a boolean.

updateDuration(email, token, task_id, duration)

Updates the duration of one of your tasks.

Returns a boolean.

newTask(email, token, sheet_id, ref, duration, created_at, description)

Create a new task, with:

Returns a boolean.

updateTask(email, token, id, ref, duration, created_at, completed_at, description, state)

Update a task which has an id of the supplied id. All parameters will be replaced, so if you do not wish to replace ‘description’ or any other field, make sure you load a task first with getTask to get the current parameters.

Returns a boolean.

destroyTask(email, token, id)

Destroy the task with ‘id’. This is not recoverable.

Returns a boolean.

Error reporting

Errors are supplied using XML, using a text string. For example:

<?xml version="1.0" ?>
<methodResponse>
  <fault><value><struct>
    <member>
      <name>faultCode</name>
      <value><i4>2</i4></value>
    </member>
    <member>
      <name>faultString</name>
      <value><string>request canceled: Permission denied - check your API token on your tiktrac settings page</string></value>
    </member>
  </struct></value></fault>
</methodResponse>