Version 17, last updated by Maxim Cretu at October 12, 2011 11:27 UTC

Decrease font size Decrease font size

Increase font size Increase font size

Print this page Print this page

Time Rest API

What is Rest (Representational State Transfer)?: It's an architectural style, not a standard. Find out more in the Wikipedia or read the following article if you want to know about REST in Rails

 

TABLE OF CONTENTS

  • Time Rest API
    • Time (Task) XML Representation
    • List of time entries (GET)
    • List of time entries in a portfolio
    • Create time entry (POST)
    • Show time entry (GET)
    • Update time entry (PUT)
    • Delete time entry (DELETE)
    • Time Log Rest API
      • Time Log XML Representation
      • List of time logs assigned to a task (GET)
      • Create a new time log and assign it to a task(POST)
      • Show time log (GET)
      • Update time log (PUT)
      • Delete time log (DELETE)

 

Tasks and Time Logs are our resources which can be referred to using this global identifier (URI):
http://www.assembla.com/user/time_entries/ or http://www.assembla.com/user/time_entries/<task_id>/time_logs/  respectively

Tasks store user's time entries related to space activity. This API provides the same functionality you can find through our application in https://www.assembla.com/my_tasks

Time Logs belongs to a task, their main porpouse is to log extra information related to task. It has three main fields: description (text field), data64 (binary field) and screenshot-url(URL to a screenshot). Time Logs were created to support Time Trackers that send one or more screenshots related to tasks, we recommend to use them only in similar scenarios.

To use the API you have to get Time tool installed in your space.


In which types can you retrieved the information?

Currently, only XML.

So, what can I do and how can I do it?

 

TASK XML REPRESENTATION

 

<task> 	
   <atributte>Value</atributte>
</task>

 

REQUIRED ATTRIBUTES(can't be blank)

* hours: Length of the task.

* description: Description of the task

* space_id (use space-id in XML): Space id. Userneeds to be a member of the space. Otherwise, space_id will be rejected

* begin_at (use begin-at in XML): Date and time when the task was started

* end_at (use end-at in XML): Date and time when the task was finished

 

OTHER ATTRIBUTES

* url: No format check is done here. If you want to link to an external site be sure to include "http://" protocol in your url

* ticket_number (use ticket-number in XML): Number of ticket in the space. A ticket with that number must exist in the space with space_id.

* ticket_id (use ticket-id in XML): Id (not ticket number!!!)of ticket. Ticket must belong to space with space_id. Check Ticket REST API for more information about how to retrive ticket's info like summary and id from number. If you need all the tasks assign to a ticket, check SHOW TICKET (GET) section in Ticket REST API
* job_agreement_id (use job-agreement-id in XML): Id of one of user's active Job Agreement. (Only for Staffing Tool)

READ-ONLY ATTRIBUTES (can't be modified)

* id (type="integer"): Unique identifier of the task among all spaces. You will need this value for the Task and Time Logs routes
* user_id: Id of the user that owns the task. It is automatically set from login credentials.

* billed: Boolean value to indicate if the task was used in billing system (only for Staffing Tool). You can't edit or destroy a task if billed is set to true.

* created_at (use created-at in XML): Date and time when the Task was created.

* updated_at (use updated-at in XML): Date and time when the Task was last modified.

 

IMPORTANT NOTE:

All this API methods require Basic Authentication and you will only be able to access or modify your own data.

 

LIST OF TASKS (GET)

To access the list of your tasks you need to send a GET request to: http://www.assembla.com/user/time_entries

If you want to get the response in xml format, be sure to include "Accept:application/xml" in your request header.

 

For example, if you are using curl, you will write:

curl -i -X GET -H "Accept: application/xml" http://user:password@www.assembla.com/user/time_entries

(Note: http://user:password@www.assembla.com/ is the way you use basic authentication with curl. You need to find out how to use it with your application)


RESPONSE: You will get an xml like this:

 

<tasks type="array">
  <task>
    <begin-at type="datetime">2008-04-21T03:28:00+00:00</begin-at>
    <billed type="boolean">false</billed>
    <created-at type="datetime">2008-04-21T12:29:05+00:00</created-at>
    <description>Pruebo</description>
    <end-at type="datetime">2008-04-21T03:28:00+00:00</end-at>
    <hours type="float">1.0</hours>
    <id type="integer">1</id>
    <job-agreement-id type="integer" nil="true"/>
    <space-id>cexKtSdHGr3yvpabNrdR7q</space-id>
    <updated-at type="datetime">2008-04-21T12:29:05+00:00</updated-at>
    <url nil="true"/>
    <user-id>bt92DWdHGr3yvpabNrdR7q</user-id>
  </task>
</tasks>

 

CREATE TASK (POST)

To create a new task you need to send a POST request to: http://www.assembla.com/user/time_entries/

If you want to get the response in xml format, be sure to include "Accept:application/xml" in your request header.

You can send the new task information in the request body with an XML:

 

XML Example(only for title).

Be sure to add Content-Type:application/xml to your header

<task>
	<description>Test Description</description>
</task>

 

Example XML Request with curl:

curl -i -X POST -H "Content-Type:application/xml" -H "Accept: application/xml" -d "<task><description>Test Description </description></task>" http://user:password@www.assembla.com/user/time_entries

 

 

RESPONSE:

If you success on creating the task you will get a Response with 201 Status and with the new task xml representation. If the creation fails you will get a 422 Status and an xml representation of the errors. Eg:

<errors>
	<error>End at can't be blank</error>
</errors>

 

 

SHOW TASK (GET)

To access the representation of a task you need to send a GET request to: http://www.assembla.com/user/time_entires/<task_id>

Where <task_id> is the id of the task you are trying to access that belongs to the authenticated user.

If you want to get the response in xml format, be sure to include "Accept:application/xml" in your request header.

 

For example, if you are using curl, you will write:

curl -i -X GET -H "Accept: application/xml" http://user:password@www.assembla.com/user/time_entries/1

(Note: http://user:password@www.assembla.com/ is the way you use basic authentication with curl. You need to find out how to use it with your application)


RESPONSE: You will get an xml like this, representing your  task:

 

<task>
    <begin-at type="datetime">2008-04-21T03:28:00+00:00</begin-at>
    <billed type="boolean">false</billed>
    <created-at type="datetime">2008-04-21T12:29:05+00:00</created-at>
    <description>Pruebo</description>
    <end-at type="datetime">2008-04-21T03:28:00+00:00</end-at>
    <hours type="float">1.0</hours>
    <id type="integer">1</id>
    <job-agreement-id type="integer" nil="true"/>
    <space-id>cexKtSdHGr3yvpabNrdR7q</space-id>
    <updated-at type="datetime">2008-04-21T12:29:05+00:00</updated-at>
    <url nil="true"/>
    <user-id>bt92DWdHGr3yvpabNrdR7q</user-id>
</task>

 

In case the task does not exist you will get a Not Found 404 Status in the response

 

UPDATE TASK (PUT)

To update a task you need to send a PUT request to: http://www.assembla.com/user/time_entries/<task_id>

Where <task_id> is the id of the task you are trying to update that belongs to the authenticated user.

If you want to get the response in xml format, be sure to include "Accept:application/xml" in your request header. To send the new task information (you only need to send the fields you want to update), send it in the body as it is explained in the CREATE TASK (POST) section.

 

Example XML Request with curl:

curl -i -X PUT -H "Content-Type:application/xml" -H "Accept: application/xml" -d "<task><description>Take this description</description></task>" http://user:password@www.assembla.com/user/time_entries/1

 

 

RESPONSE:

If you success on updating the task you will get a Response with 200 Status including the updated task's xml representation. If the update fails you will get a 422 Status and an xml representation of the errors.

 

 

DELETE TASK (DELETE)

To delete a task you need to send a DELETE request to: http://www.assembla.com/user/time_entries/<task_id>

Where <task_id> is the id of the task you are trying to delete that belongs to the user that is authenticated.

 

Example with curl:

curl -i -X DELETE -H "Accept: application/xml" http://user:password@www.assembla.com/user/time_entries/1

 

RESPONSE:

If you success on deleting the task you will get a Response with 200 OK Status. If the task is not found you will get a 404 Not Found Status.

IMPORTANT:

Deleting a Task automatically deletes all the time logs assigned to it

TIME LOG XML REPRESENTATION

 

<time-log> 	
   <atributte>Value</atributte>
</time-log>

 

ATTRIBUTES (none is required)

* description: Description that represents

* data64: Binary data encoded in Base64

* screenshot-url: URL to an image (this will work the same as data64 field, but instead of encoded binary data you provide a URL)

* is_timeout (use is-timeout in XML): Boolean field. Name is only for legacy support and does not provide any special behaviour.

Note:data64 and screenshot-url will upload the image as an attachment to time log, maximum image size is 1 MB.

READ-ONLY ATTRIBUTES (can't be modified)

* id (type="integer"): Unique identifier of the time log among all spaces. You will need this value for the Time Logs routes
* user_id: Id of the user that owns the time log (the same user than the task). It is automatically set from login credentials.

* space_id: Id of the space which the time log belongs to (the same space than the one in the task).

* task_id: Id of the task which the time log belongs to.

* screenshot (type="binary" encoding="base64"): Stored binary data (which can be set through data64 or screenshot-url field)

* created_at (use created-at in XML): Date and time when the Task was created.

 

IMPORTANT NOTE:

All this API methods require Basic Authentication and you will only be able to access or modify your own data.

 

LIST OF TIME LOGS (GET)

To access the list of the time logs that belongs to a task you need to send a GET request to: http://www.assembla.com/user/time_entries/<task_id>/time_logs

If you want to get the response in xml format, be sure to include "Accept:application/xml" in your request header.

 

For example, if you are using curl, you will write:

curl -i -X GET -H "Accept: application/xml" http://user:password@www.assembla.com/user/time_entries/1/time_logs

(Note: http://user:password@www.assembla.com/ is the way you use basic authentication with curl. You need to find out how to use it with your application)


RESPONSE: You will get an xml like this:

 

<time-logs type="array">
  <time-log>
    <created-at type="datetime">2009-02-19T16:55:33+00:00</created-at>
    <description nil="true"/>
    <id type="integer">1</id>
    <is-timeout type="boolean">false</is-timeout>
    <screenshot type="binary" encoding="base64" nil="true"/>
    <space-id>cexKtSdHGr3yvpabNrdR7q</space-id>
    <task-id type="integer">1</task-id>
    <user-id>bt92DWdHGr3yvpabNrdR7q</user-id>
  </time-log>
</time-logs>

 

CREATE TIME LOG (POST)

To create a new time log and assign it to a task you need to send a POST request to: http://www.assembla.com/user/time_entries/<task_id>/time_logs

If you want to get the response in xml format, be sure to include "Accept:application/xml" in your request header.

You can send the new time log information in the request body with an XML:

 

XML Example(only for title).

Be sure to add Content-Type:application/xml to your header

<time-log>
	<description>Test Description</description>
</time-log>

 

Example XML Request with curl:

curl -i -X POST -H "Content-Type:application/xml" -H "Accept: application/xml" -d "<time-log><description>Test Description </description></time-log>" http://user:password@www.assembla.com/user/time_entries/1/time_logs/

 

 

RESPONSE:

If you success on creating the time log you will get a Response with 201 Status and with the new time_log xml representation. If the creation fails you will get a 422 Status and an xml representation of the errors. Eg:

<errors>
	<error>Error ocurred while.....</error>
</errors>

 

 

SHOW TIME LOG (GET)

To access the representation of a time log you need to send a GET request to: http://www.assembla.com/user/time_entires/<task_id>/time_logs/<time_log_id>

Where <time_log_id> is the id of the time log you are trying to access and <task_id> is the id of the task which this time log belongs to.

If you want to get the response in xml format, be sure to include "Accept:application/xml" in your request header.

 

For example, if you are using curl, you will write:

curl -i -X GET -H "Accept: application/xml" http://user:password@www.assembla.com/user/time_entries/1/time_logs/1

(Note: http://user:password@www.assembla.com/ is the way you use basic authentication with curl. You need to find out how to use it with your application)


RESPONSE: You will get an xml like this, representing your time log:

 

<time-log>
    <created-at type="datetime">2009-02-19T16:55:33+00:00</created-at>
    <description nil="true"/>
    <id type="integer">1</id>
    <is-timeout type="boolean">false</is-timeout>
    <screenshot type="binary" encoding="base64" nil="true"/>
    <space-id>cexKtSdHGr3yvpabNrdR7q</space-id>
    <task-id type="integer">1</task-id>
    <user-id>bt92DWdHGr3yvpabNrdR7q</user-id>
</time-log>

 

IMPORTANT: In case the time log does not exist or the taskdoes not match you will get a Not Found 404 Status in the response

 

UPDATE TIME LOG (PUT)

To update a time log you need to send a PUT request to: http://www.assembla.com/user/time_entries/<task_id>/time_logs/<time_log_id>

Where <time_log_id> is the id of the time log you are trying to update and <task_id> is the id of the task which the time log belongs to.

If you want to get the response in xml format, be sure to include "Accept:application/xml" in your request header. To send the new time log information (you only need to send the fields you want to update), send it in the body as it is explained in the CREATE TIME LOG (POST) section.

 

Example XML Request with curl:

curl -i -X PUT -H "Content-Type:application/xml" -H "Accept: application/xml" -d "<time-log><description>Take this description</description></time-log>" http://user:password@www.assembla.com/user/time_entries/1/time_logs/1

 

RESPONSE:

If you success on updating the time log you will get a Response with 200 Status including the updated time log's xml representation. If the update fails you will get a 422 Status and an xml representation of the errors.

 

 

DELETE TIME LOG (DELETE)

To delete a time log you need to send a DELETE request to: http://www.assembla.com/user/time_entries/<task_id>/time_logs/<time_log_id>

Where <time_log_id> is the id of the time log you are trying to delete and <task_id> is the id of the task which the time log belongs.

 

Example with curl:

curl -i -X DELETE -H "Accept: application/xml" http://user:password@www.assembla.com/user/time_entries/1/time_logs/1

 

RESPONSE:

If you success on deleting the time_log you will get a Response with 200 OK Status. If the time_log is not found or if the task does not match you will get a 404 Not Found Status.


EXPORT TIME LOG

You are allowed to check the time entries of user in one space by sending a GET request to

https://www.assembla.com/spaces/<space_id>/time_entries/export
curl example: 
curl -i -H "Accept: application/xml" https://user:password@www.assembla.com/spaces/<space_id>/time_entries/export

Be sure to use HTTPS instead of HTTP

Request can accept the following options

from_date = Date (YYYY/MM/DD)
until_date = Date (YYYY/MM/DD)
users[] = user_id
curl example: 
curl -i -X GET -H "Accept: application/xml" -d "from_date=2010/11/17" -d "until_date=2010/11/20" https://user:password@www.assembla.com/spaces/<space_id>/time_entries/export
users[] is an HTTP array, so you can use it many times, curl example: 
curl -i -X GET -H "Accept: application/xml" -d "from_date=2010/11/17" -d "until_date=2010/11/20"  -d "users[]=<user_id>" -d "users[]=<user_id>" https://user:password@www.assembla.com/spaces/<space_id>/time_entries/export

TIME LOG REPORT FOR A PORTFOLIO

To get the list of time logs for a portfolio you can send a GET request to: https://login:password@your_portfolio.assembla.com/p/time

By default the result will be all time entries inside a portfolio for last 7 days.

Query can accept some filtering options:

Option Values Description
from_date yyyy/mm/dd Date from time logs should be present
until_date yyyy/mm/dd Date until time logs should be present
billed_or_paid It takes one of options: All, Billed, Un-Billed, Not-Billable, Paid, Un-Paid, Not-Payable Filter records by a specific state
filter[spacegroup] To be able to filter records by spaces you have to create a filter from the UI first in Time tab Filters pane, then, pickup the id of the filter from the url when you access the filter, it will be contained in filter[spacegroup]=:filter_id Filter records by spaces
filter[usergroup] To be able to filter records by users you have to create a filter from the UI first in Time tab Filters pane, then, pickup the id of the filter from the url when you access the filter, it will be contained in filter[usergroup]=:filter_id Filter records by users

Example output for a task list:

<?xml version="1.0" encoding="UTF-8"?>
<tasks type="array">
  <task>
    <created-at type="datetime">2011-10-12T13:19:22Z</created-at>
    <begin-at type="datetime">2011-10-12T13:19:00Z</begin-at>
    <updated-at type="datetime">2011-10-12T13:19:22Z</updated-at>
    <end-at type="datetime">2011-10-12T13:19:00Z</end-at>
    <url nil="true"></url>
    <ticket-id type="integer" nil="true"></ticket-id>
    <id type="integer">6</id>
    <billed type="boolean">false</billed>
    <user-id>aIJbLeNzir4jAWadbNA33N</user-id>
    <description>sfsdfsd</description>
    <hours type="float">1.0</hours>
    <job-agreement-id type="integer" nil="true"></job-agreement-id>
    <space-id>b89TL8MYWr4id7adbNA33N</space-id>
    <ticket-number type="yaml" nil="true"></ticket-number>
  </task>
  <task>
    <created-at type="datetime">2011-10-12T13:19:30Z</created-at>
    <begin-at type="datetime">2011-10-11T13:19:00Z</begin-at>
    <updated-at type="datetime">2011-10-12T13:19:30Z</updated-at>
    <end-at type="datetime">2011-10-11T13:19:00Z</end-at>
    <url nil="true"></url>
    <ticket-id type="integer" nil="true"></ticket-id>
    <id type="integer">7</id>
    <billed type="boolean">false</billed>
    <user-id>aIJbLeNzir4jAWadbNA33N</user-id>
    <description>ggfff</description>
    <hours type="float">1.0</hours>
    <job-agreement-id type="integer" nil="true"></job-agreement-id>
    <space-id>b89TL8MYWr4id7adbNA33N</space-id>
    <ticket-number type="yaml" nil="true"></ticket-number>
  </task>
</tasks>

Example requests using cURL:

Default report for 1 week

curl -H "Accept: application/xml" https://user:password@assembla-inc.assembla.com/p/time

Applying some filtering

curl -H "Accept: application/xml" -d "from_date=2011/10/10" -d "until_date=2011/10/12" -d "billed_or_paid=Un-Billed" https://user:password@assembla-inc.assembla.com/p/time

Filter by spaces

Assume your space filter id is 1

curl -H "Accept: application/xml" -d "filter[spacegroup]=1" https://user:password@assembla-inc.assembla.com/p/time

Filter by users

Assume your space filter id is 1

curl -H "Accept: application/xml" -d "filter[usergroup]=1" https://user:password@assembla-inc.assembla.com/p/time