Overview

LiveTimer exposes most of its functionality via an Application Programming Interface (API), which enables developers to build applications that interact with LiveTimer. This could be useful if, for instance, you want to integrate your LiveTimer account with your company's project management or accounting systems.

The LiveTimer API adheres to the REST principles as closely as possible. Resources, such as projects, users and time entries, each have a unique URI. These resources are controlled using the primary HTTP verbs: GET, POST, PUT AND DELETE. Data is returned in XML format.

Security and Authentication

The LiveTimer API uses HTTP basic authentication to identify users. Users are identified with the same user names and passwords that are used by the web interface. Of course, users have the same permissions to view and modify data using the API as they do using the web interface.

The API requires the use of HTTPS to transmit all data, including authentication credentials, securely from client applications to LiveTimer's servers. Therefore, LiveTimer's API is every bit as secure as its web interface.

Getting Started

Using a Web Browser

Perhaps the easiest way to try out the API is with your web browser, which issues an HTTP GET request whenever you type in a URL. Certain browsers are better than others for displaying XML data - we recommend using Firefox or Camino for a quick test of the API. Just browse to any resource in your LiveTimer account, such as a project, and then append .xml to the URL. You should be prompted for your user name and password and then should see an XML representation of that resource.

For example, we can browse to the following URL for our sample "artworks" account:

https://artworks.livetimer.com/projects/28.xml

After entering a valid user name and password, this yields the following result:

<project>
  <id type="integer">28</id>
  <name>Irises</name>
  <active type="boolean">true</active>
  <effectively-active type="boolean">true</effectively-active>
  <code/>
  <description>Remove gum from corner of painting.</description>
  <url/>
  <client-id type="integer">22</client-id>
  <created-at type="datetime">2007-03-30T20:32:06Z</created-at>
  <updated-at type="datetime">2008-01-04T02:39:00Z</updated-at>
</project>

Using cURL

cURL is a command line tool included with many operating systems. If you do not have cURL installed, you can download it here. cURL provides a more thorough means of testing the API than your browser, since it makes it easy to issue requests with verbs other than GET.

The following cURL request returns the same XML as the sample above (note: the fake username and password prevent this example from returning successfully):

curl -u username:password -H 'Accept: application/xml' 'https://artworks.livetimer.com/projects/28.xml'

You may find it helpful to run cURL in verbose mode in order to see the full details of both your requests and LiveTimer's responses. Verbose mode is enabled by including the -v option.

The following examples illustrate the use of cURL to create, read, update and delete data (commonly referred to as CRUD operations).

Reading Data

Data should be requested using the HTTP verb GET. Because GET is the default verb for most HTTP clients, including cURL, it is probably not necessary to explicitly specify the GET verb with your data requests.

It is recommended that you specify the header 'Accept: application/xml' to indicate that your application expects XML to be returned. In the future, LiveTimer may return data in multiple formats, so specifying this header guarantees that your application will always receive XML results.

A status of '200 OK' will be returned with a successful request to read data.

Working with Arrays

We've already seen an example of using cURL to return a single resource's data (see above). LiveTimer also provides a number of methods which return arrays of resources. For example, the following request returns all the projects in our sample account:

curl -u username:password -H 'Accept: application/xml' 'https://artworks.livetimer.com/projects.xml'

This request returns multiple <project> tags wrapped in a single <projects> tag. Note the total, start, and end attributes on the <projects> tag:

<projects total="6" end="6" start="1">
  <project>
    <id type="integer">26</id>
    <name>The Scream</name>
    <active type="boolean">true</active>
    <effectively-active type="boolean">true</effectively-active>
    <code nil="true"/>
    <description>Repair water damage.</description>
    <url nil="true"/>
    <client-id type="integer">21</client-id>
    <created-at type="datetime">2007-03-30T02:25:21Z</created-at>
    <updated-at type="datetime">2007-12-20T06:55:23Z</updated-at>
  </project>
  ...
</projects>

LiveTimer follows this same convention for all methods that return arrays of resources. Each request can return a maximum of 50 array members, so please check the total, start, and end attributes carefully.

You may page through resources by including start and / or end parameters with your requests. For example, the following request returns the first three projects:

curl -u username:password -H 'Accept: application/xml' 'https://artworks.livetimer.com/projects.xml?start=1&end=3'

Including Related Records

By minimizing the number of API calls your application makes you can maximize its performance. For this reason, we've designed many methods to accept an optional include parameter, which allows related records to be returned with a single request.

For instance, the following request returns projects assigned to the current user, complete with related clients and tasks:

curl -u username:password -H 'Accept: application/xml' 'https://artworks.livetimer.com/projects/my_assignments.xml?include=clients,tasks'

The API documentation explains the optional include parameters allowed for each API method.

Writing Data

Writing data should be done with the appropriate HTTP verb: POST to create resources, PUT to update resources, and DELETE to delete resources.

As when reading data, it is recommended that you specify the header 'Accept: application/xml' to indicate that you'd like data returned as XML. Furthermore, specify the header 'Content-Type:application/xml' whenever including XML data with your request.

Creating Resources

Use the POST verb to create resources. The following request will create a new project named 'Test' in our sample account:

curl -u username:password -X POST -H 'Accept: application/xml' -H 'Content-Type:application/xml' 'https://artworks.livetimer.com/projects' -d '<project><name>Test</name><client_id>22</client_id></project>'

A status of '201 Created' will be returned with a successful request to create a resource. In addition, the newly created resource's data will be returned.

Updating Resources

Use the PUT verb to update resources. The following request will change the client that the above project is associated with:

curl -u username:password -X PUT -H 'Accept: application/xml' -H 'Content-Type:application/xml' 'https://artworks.livetimer.com/projects/536.xml' -d '<project><client_id>24</client_id></project>'

A status of '200 OK' will be returned with a successful request to update a resource.

Deleting Resources

Use the DELETE verb to delete resources. The following request will delete the project just created above:

curl -u username:password -X DELETE -H 'Accept: application/xml' 'https://artworks.livetimer.com/projects/536.xml'

A status of '200 OK' will be returned with a successful request to delete a resource.

General notes

Status Codes

Whenever possible, the appropriate HTTP status codes will be returned to indicate whether LiveTimer could successfully respond to a request. Here are some of the most common status codes that you may encounter:

• 200 OK - Your request to retrieve, update or delete data was successful.
• 201 Created - A resource was successfully created.
• 401 Unauthorized - You are not authorized to perform the requested operation.
• 404 Not Found - The requested resource could not be found.
• 422 Unprocessable Entity - Your request could not be processed. An explanation should be returned as data.

XML Data Types

Data types other than strings are specified with the type attribute. The following data types are used by this API:

• integer - Every resource is uniquely identified with an integer ID.
• boolean - Simply true or false.
• date - A date with a format of YYYY-MM-DD. For example, 2008-01-21 is January 21st, 2008.
• datetime - A date and time format of YYYY-MM-DDThh:mm:ssZ, which includes the time zone offset (Z). For example, 2008-01-06T16:01:00-05:00 is 4:01pm on January 6, 2008 UTC-05. 2008-01-06T16:01:00Z is also 4:01pm on January 6, 2008, but is UTC. Times are almost exclusively returned in UTC, with the notable exception of time entry start / end times.

Custom Classifications and Terminology

LiveTimer supports many customizations, including which classifications are enabled for your account as well as the terminology used to describe these classifications. These customizations can be changed for your account by an Administrator using LiveTimer's web interface.

The API refers to classifications by their default names: clients, projects, tasks and activities. However, methods are included to determine which classifications are in use for your account, as well as any custom terminology used (see General Information).

---

This concludes the introduction to LiveTimer API. If you have any questions or feedback, please email us at support AT livetimer DOT com.

Please continue to read the detailed documentation for the LiveTimer API.

Continue to General Information...