Assembla DocumentationPublic Space

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

• Ticket Rest API
  • Ticket XML Representation
  • List of tickets (GET)
  • Create ticket (POST)
  • Show ticket(GET)
  • Update ticket (PUT)
  • List of comments (GET)

TICKET REST API

Tickets are our resources here which can be referred to using this global identifier (URI):
http://www.assembla.com/spaces/<space_id>/tickets/

Where <space_id> is the id of the space with the Ticket Tool you are trying to access.

In which types can you retrieved the information?

Currently, HTML or XML. HTML is what you already have in your Ticket Tool. What we add now is the possibility to retrieve the information in other types (for now, xml).

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

TICKET XML REPRESENTATION

<ticket> 	
   <atributte>Value</atributte>
</ticket>

REQUIRED ATTRIBUTES (can't be blank)

* number (type="integer"): Ticket number. You must use this number in the tickets url to access the methods (show,update). You can change it, but you are encourage not to. You should not repeat ticket numbers in the same space
* summary: Summary of the ticket
* reporter-id: Id of user who report the ticket. Automatically fill on create with your user (or with acts_as_user_id in case you are using that functionallity).
* priority (type="integer"): Must be between 1 and 5.
* status (type="integer"): Number between 0 and 4.

OTHER ATTRIBUTES

* description: Description of the ticket
* user-comment: Include this field in your ticket and a comment will be added attached to your ticket.
* assigned-to-id: Id of user assigned to the ticket.
* milestone-id (type="integer"): Id of the milestones assigned to the ticket
* component-id: Id of component assigned to the ticket.
* user-comment: Only available when updating tickets to add a user comment to the changes.
* created-on (type="datetime"): Create date of ticket. Automatically completed but you can modify if you want (only when creating a ticket. You can't change it with an update ticket request).
* updated-at: Automatically fill on every update.
* acts_as_user_id: Id of user you want to act as. Logged user must have ALL priviliges in the space in order to act as another user. This fields allow you to create tickets, update changes or add comments as other users (of special interest during imports from other systems).
* skip_alerts: Default: false. Set it to true if you want to avoid generating alerts when a ticket is created or updated. User must have ALL priviliges in the space to set skip_alerts to true.

* working_hour: Work hours remaining for the ticket.

SYSTEM ATTRIBUTES (can't be modified)

* id (type="integer"): Unique identifier of the ticket among all spaces. This value is not the one you use in the ticket routes (See number attribute). You may only use this value in the documents api
* space-id: Id of the space the ticket belongs to.

LIST OF TICKETS (GET)

To access the list of your tickets you need to send a GET request to: http://www.assembla.com/spaces/<space_id>/tickets/

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/spaces/my_space_id/tickets

(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:

<tickets>

	<ticket>
		<assigned-to-id></assigned-to-id>
		<component-id type="integer"></component-id>
		<created-on type="datetime">2007-12-03T09:57:47-03:00</created-on>

		<description>This is the ticket description</description>
		<milestone-id type="integer"></milestone-id>
		<number type="integer">1</number>
		<priority type="integer">3</priority>

		<reporter-id>user_id</reporter-id>
		<space-id>space_id</space-id>
		<status type="integer">0</status>
		<summary>This is the summary</summary>

		<updated-at type="datetime">2007-12-03T11:12:01-03:00</updated-at>	

              <working_hour type="float">4.0</working_hour>

</ticket>

</tickets>

If you created some Custom Fields from the Ticket Settings page, for example:

 You will get another RESPONSE:

	<ticket>
		<assigned-to-id></assigned-to-id>
		<component-id type="integer"></component-id>
		<created-on type="datetime">2007-12-03T09:57:47-03:00</created-on>

		<description>This is the ticket description</description>
		<milestone-id type="integer"></milestone-id>
		<number type="integer">1</number>
		<priority type="integer">3</priority>

		<reporter-id>user_id</reporter-id>
		<space-id>space_id</space-id>
		<status type="integer">0</status>
		<summary>This is the summary</summary>

		<updated-at type="datetime">2007-12-03T11:12:01-03:00</updated-at>

               <working_hour type="float">4.0</working_hour>

   <CustomFields>
     <CustomField name="Type" type="List">defect</CustomField>
     <CustomField name="Version" type="Text">1.0</CustomField>
     <CustomField name="Team List" type="Team List">aGgivCEQar3AwZabTJSnCg</CustomField>
     <CustomField name="Date" type="Date">2008/09/10</CustomField>
   </CustomFields> 

            </ticket>

</tickets>

If you also add a parameter called tickets_report_id in your request with a number between 0 to 11, you will get one of the following lists:

E.g: curl -i -X GET -H "Accept: application/xml" http://user:password@www.assembla.com/spaces/my_space_id/tickets?tickets_report_id=5

CREATE TICKET (POST)

To create a new ticket you need to send a POST request to: http://www.assembla.com/spaces/<space_id>/tickets/

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 ticket information in the request body in two ways: Submiting a form with post method and rails convention for names OR with an XML:

Form Example(only for summary)

<form action="www.assembla.com/spaces/my_space_id/tickets/" method="post">
	<input type="text" value="This is a Summary" name="ticket[summary]" id="ticket_summary" />
</form>

XML Example(only for summary).

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

<ticket>
	<summary>This is a summary</summary>

</ticket> 

Example XML Request with curl:

curl -i -X POST -H "Content-Type:application/xml" -H "Accept: application/xml" -d "<ticket><summary>This is a Summary</summary><priority>3</priority></ticket>" http://user:password@www.assembla.com/spaces/my_space_id/tickets

Example Form Request with curl:

curl -i -X POST -H "Accept: application/xml" -d "ticket[summary]=My Summary&ticket[priority]=3" http://user:password@www.assembla.com/spaces/my_space_id/tickets

Form Example(with custom_fields)

<form action="www.assembla.com/spaces/my_space_id/tickets/" method="post">

  <input type="text" name="ticket[working_hour]" id="ticket_working_hour"/>

  <input type="text" name="ticket[custom_fields][1]" id="ticket[custom_fields][1]"/> 

<select name="ticket[custom_fields][2]" id="ticket[custom_fields][2]">

<option value=""/>
<option value="low">low</option>
<option value="high">high</option>

</select> 

</form> 

 where [1] - 1, it's an id of Custom Field with type Text,

  and [2] - 2, it's an id of Custom Field with type List.

RESPONSE:

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

<errors>
	<error>Summary can't be blank</error>
</errors> 

SHOW TICKET (GET)

To access the representation of a simple ticket you need to send a GET request to: http://www.assembla.com/spaces/<space_id>/tickets/<ticket_number>

Where <ticket_number> is the number of the ticket you are trying to access that belongs to the space with <space_id>

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/spaces/my_space_id/tickets/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 ticket:

<ticket>
	<assigned-to-id></assigned-to-id>
	<component-id type="integer"></component-id>
	<created-on type="datetime">2007-12-03T09:57:47-03:00</created-on>

	<description>This is the ticket description</description>
	<milestone-id type="integer"></milestone-id>
	<number type="integer">1</number>
	<priority type="integer">3</priority>

	<reporter-id>user_id</reporter-id>
	<space-id>space_id</space-id>
	<status type="integer">0</status>
	<summary>This is the summary</summary>

	<updated-at type="datetime">2007-12-03T11:12:01-03:00</updated-at>	
</ticket>

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

UPDATE TICKET (PUT)

To update a simple ticket you need to send a PUT request to: http://www.assembla.com/spaces/<space_id>/tickets/<ticket_number>

Where <ticket_number> is the number of the ticket you are trying to update that belongs to the space with <space_id>

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 ticket information, send it in the body as it is explained in the CREATE TICKET (POST) section.

Example XML Request with curl:

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

Example Form Request with curl:

curl -i -X PUT -H "Accept: application/xml" -d "ticket[description]=Take this description" http://user:password@www.assembla.com/spaces/my_space_id/tickets/1

RESPONSE:

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

LIST OF COMMENTS (GET)

To access the list of your tickets you need to send a GET request to: http://www.assembla.com/spaces/<space_id>/tickets/<ticket_number>/comments

If you want to get the response in xml format, be sure to include "Accept:application/xml" in your request header (XML is the only format supported right now).

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

curl -i -X GET -H "Accept: application/xml" http://user:password@www.assembla.com/spaces/my_space_id/ticket/ticket_number/comments

(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)

Eg: https://www.assembla.com/spaces/breakout/tickets/2823/comments.xml

NOTES:

1) You need to have Ticket Tool installed in you space to access this API.