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
Milestones are our resources here which can be referred to using this global identifier (URI):
http://www.assembla.com/spaces/<space_id>/milestones/
Where <space_id> is the id of the space with the Milestone 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 Milestone 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?
<milestone> <atributte>Value</atributte> </milestone>
REQUIRED ATTRIBUTES (can't be blank)
* title: Milestone's title
OTHER ATTRIBUTES
* description: Description of the milestone.
* user-id: Id of user responsible for this milestone.
* due-date (type="date"): Milestone's due date
* is-completed (type="boolean"): Set to true if the milestone is completed
* completed-date (type="date"): Automatically filled when is-completed is set to true but you may set your own value.
* created-by: Id of the user who created the milestone. Automatically filled with your user, but you can change it when creating a milestone. You are not allowed to when updating a milestone.
* created-at (type="datetime"): Date and time when the milestone was created. Automatically filled, but you can change it when creating a milestone. You are not allowed to when updating a milestone.
* skip_alerts (type="boolean"): Default: false. Set it to true if you want to avoid generating alerts when a milestone is created. User must have ALL priviliges in the space to set skip_alerts to true.
READ-ONLY ATTRIBUTES (can't be modified)
* id (type="integer"): Unique identifier of the milestone among all spaces. You will need this value for the milestone routes
* space-id: Id of the space the milestone belongs to.
To access the list of your milestones you need to send a GET request to: http://www.assembla.com/spaces/<space_id>/milestones/
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/milestones
(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:
<milestones> <milestone> <completed-date type="date">2007-12-01</completed-date> <created-at type="datetime">2007-10-08T01:15:30-03:00</created-at> <created-by>user_id</created-by> <description>This is a test milestone</description> <due-date type="date">2007-12-15</due-date> <id type="integer">1</id> <is-completed type="boolean">true</is-completed> <space-id>my_space</space-id> <title>Test Milestone</title> <user-id>user_id</user-id> </milestone> </milestones>
There is an optional parameter you may add called voption. This parameters will let you filter the milestone list, the possible values are the followings:
| all | List all the milestones |
| late | List of late milestones (who has passed their due date and are not completed) |
| upcoming | List of upcoming milestones (who has not passed their due date and are not completed) |
| completed | List of completed milestones |
Example with curl:
curl -i -X GET -H "Accept: application/xml" http://user:password@www.assembla.com/spaces/my_space_id/milestones?voption=late
To create a new milestone you need to send a POST request to: http://www.assembla.com/spaces/<space_id>/milestones/
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 milestone information in the request body in two ways: Submitting a form with post method and rails convention for names OR with an XML:
Form Example(only for title)
<form action="www.assembla.com/spaces/my_space_id/milestone/" method="post"> <input type="text" value="Test Milestone" name="milestone[title]" id="milestone_title" /> </form>
XML Example(only for title).
Be sure to add Content-Type:application/xml to your header
<milestone> <title>Test Milestone</title> </milestone>
Example XML Request with curl:
curl -i -X POST -H "Content-Type:application/xml" -H "Accept: application/xml" -d "<milestone><title>Test Milestone</title></milestone>" http://user:password@www.assembla.com/spaces/my_space_id/milestones
Example Form Request with curl:
curl -i -X POST -H "Accept: application/xml" -d "milestone[title]=Test Milestone&milestone[description]=This is a test milestone" http://user:password@www.assembla.com/spaces/my_space_id/milestones
RESPONSE:
If you success on creating the milestone you will get a Response with 201 Status and with the new milestone xml representation. If the creation fails you will get a 422 Status and an xml representation of the errors. Eg:
<errors> <error>Title can't be blank</error> </errors>
To access the representation of a simple milestone you need to send a GET request to: http://www.assembla.com/spaces/<space_id>/milestones/<milestone_id>
Where <milestone_id> is the id of the milestone 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/milestones/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 milestone:
<milestone> <completed-date type="date">2007-12-01</completed-date> <created-at type="datetime">2007-10-08T01:15:30-03:00</created-at> <created-by>user_id</created-by> <description>This is a test milestone</description> <due-date type="date">2007-12-15</due-date> <id type="integer">1</id> <is-completed type="boolean">true</is-completed> <space-id>my_space</space-id> <title>Test Milestone</title> <user-id>user_id</user-id> </milestone>
In case the milestone does not exist you will get a Not Found 404 Status in the response
To update a simple milestone you need to send a PUT request to: http://www.assembla.com/spaces/<space_id>/milestones/<milestone_id>
Where <milestone_id> is the id of the milestone 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 milestone information, send it in the body as it is explained in the CREATE MILESTONE (POST) section.
Example XML Request with curl:
curl -i -X PUT -H "Content-Type:application/xml" -H "Accept: application/xml" -d "<milestone><description>Take this description</description></milestone>" http://user:password@www.assembla.com/spaces/my_space_id/milestones/1
Example Form Request with curl:
curl -i -X PUT -H "Accept: application/xml" -d "milestone[description]=Take this description" http://user:password@www.assembla.com/spaces/my_space_id/milestones/1
RESPONSE:
If you success on updating the milestone you will get a Response with 200 Status including the updated milestone's xml representation. If the update fails you will get a 422 Status and an xml representation of the errors.
To delete a simple milestone you need to send a DELETE request to: http://www.assembla.com/spaces/<space_id>/milestones/<milestone_id>
Where <milestone_id> is the id of the milestone you are trying to update that belongs to the space with <space_id>
Example with curl:
curl -i -X DELETE -H "Accept: application/xml" http://user:password@www.assembla.com/spaces/my_space_id/milestones/1
RESPONSE:
If you success on deleting the milestone you will get a Response with 200 OK Status. If the milestone is not found you will get a 404 Not Found Status.
NOTES:
1) You need to have Milestone Tool installed in you space to access this API.