Version 12, last updated by Maxim Cretu at July 26, 2011 05:39 UTC
Milestone 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
- Milestone Rest API
- Milestone XML Representation
- List of milestones (GET)
- Create milestone (POST)
- Show milestone (GET)
- Update milestone (PUT)
- Delete milestone (DELETE)
- Milestone filters (GET)
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.
* release_level (type="integer"): Default: null. Indicates release level with next codes: "1" - Alpha, "2" - Beta, "3" - Stable.
* release_notes Default: null. Enter milestone notes when you have completed the milestone and you are ready to attach files that contain the milestone package
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 type="array">
<milestone>
<completed-date type="date" nil="true"></completed-date>
<created-at type="datetime">2010-07-22T14:04:11+03:00</created-at>
<created-by>bgnP_qA1Gr2QjIaaaHk9wZ</created-by>
<description>Hello world description</description>
<due-date type="date" nil="true"></due-date>
<id type="integer">15</id>
<is-completed type="boolean">false</is-completed>
<release-level type="integer">2</release-level>
<release-notes>This release will contain something cool</release-notes>
<space-id>at6CkKLwSr34lqacjKAZfO</space-id>
<title>My release</title>
<updated-at type="datetime">2010-07-23T14:56:03+03:00</updated-at>
<updated-by>bgnP_qA1Gr2QjIaaaHk9wZ</updated-by>
<user-id></user-id>
<pretty-release-level>Beta</pretty-release-level>
<documents type="array">
<document>
<filesize type="integer">139856</filesize>
<name>BDD_Intro.pdf</name>
<url>http://www.assembla.com/spaces/sap_releases/documents/afJu4MMUyr350kacjKAZfO/download/File1.pdf</url>
</document>
<document>
<filesize type="integer">131988</filesize>
<name>CodeConventions.pdf</name>
<url>http://www.assembla.com/spaces/sap_releases/documents/ah6L28MUyr350kacjKAZfO/download/File2.pdf</url>
</document>
</documents>
</milestone>
</milestones>
Results are listed in pages with 20 results per page. To get the contents of a page you should pass the page=<page_number> parameter, to get results from the page 2 you can use a curl query like next:
curl -H "Accept: application/xml" http://user:password@www.assembla.com/spaces/my_space_id/milestones?page=2
To get results from next page just increment page's parameter value.
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:
| 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.
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
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" nil="true"></completed-date>
<created-at type="datetime">2010-07-22T14:04:11+03:00</created-at>
<created-by>bgnP_qA1Gr2QjIaaaHk9wZ</created-by>
<description>Hello world description</description>
<due-date type="date" nil="true"></due-date>
<id type="integer">15</id>
<is-completed type="boolean">false</is-completed>
<release-level type="integer">2</release-level>
<release-notes>This release will contain something *cool*</release-notes>
<space-id>at6CkKLwSr34lqacjKAZfO</space-id>
<title>Hello world!</title>
<updated-at type="datetime">2010-07-23T14:56:03+03:00</updated-at>
<updated-by>bgnP_qA1Gr2QjIaaaHk9wZ</updated-by>
<user-id></user-id>
<pretty-release-level>Beta</pretty-release-level>
<documents type="array">
<document>
<filesize type="integer">139856</filesize>
<name>BDD_Intro.pdf</name>
<url>http://www.assembla.com/spaces/sap_releases/documents/afJu4MMUyr350kacjKAZfO/download/BDD_Intro.pdf</url>
</document>
<document>
<filesize type="integer">131988</filesize>
<name>CodeConventions.pdf</name>
<url>http://www.assembla.com/spaces/sap_releases/documents/ah6L28MUyr350kacjKAZfO/download/CodeConventions.pdf</url>
</document>
<document>
<filesize type="integer">10752</filesize>
<name>Oferta.xls</name>
<url>http://www.assembla.com/spaces/sap_releases/documents/aKsEkoMTWr350kacjKAZfO/download/Oferta.xls</url>
</document>
<document>
<filesize type="integer">131988</filesize>
<name>CodeConventions.pdf</name>
<url>http://www.assembla.com/spaces/sap_releases/documents/c2ijHcMWqr350kacjKAZfO/download/CodeConventions.pdf</url>
</document>
</documents>
</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
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.
MILESTONE FILTERS (GET)
Milestones have 4 available filters.
- All milestones
- Upcoming milestones (default)
- Completed milestones
- Releases
Note: By default milestones are sorted by due date in ascendant order. To change order, send "milestone_sort_id=DESC" parameter with the request ( -d "milestone_sort_id=DESC" in case of cURL command. ).
E.g. curl -i -X GET -H "Content-Type:application/xml" -H "Accept: application/xml" -d "milestone_sort_id=DESC" http://user:password@www.assembla.com/spaces/<space_id>/milestones/
1. All milestones can be accessed requesting them with GET from http://www.assembla.com/spaces/milestones/all/<space_id>
curl command: curl -i -X GET -H "Content-Type:application/xml" -H "Accept: application/xml" http://user:password@www,assembla.com/spaces/milestones/all/<space_id>
2. Completed milestones can be accessed requesting them with GET from http://www.assembla.com/spaces/milestones/completed/<space_id>
curl command: curl -i -X GET -H "Content-Type:application/xml" -H "Accept: application/xml" http://user:password@www.assembla.com/spaces/milestones/completed/<space_id>
3. Releases milestones, will show all milestones with release notes. Can be accessed requesting them with GET from http://www.assembla.com/spaces/milestones/release_notes/<space_id>
curl command: curl -i -X GET -H "Content-Type:application/xml" -H "Accept: application/xml" http://user:password@www.assembla.com/spaces/milestones/release_notes/<space_id>
4. Upcoming milestones, this is the default filter and is called when index action is called. Can be accessed requesting it with GET from http://www.assembla.com/spaces/milestones/upcoming/<space_id>
curl command: curl -i -X GET -H "Content-Type:application/xml" -H "Accept: application/xml" http://user:password@www.assembla.com/spaces/milestones/upcoming/<space_id>
Note: The output will be the same as getting list of milestones, but filtered and ordered.
NOTES:
1) You need to have Milestone Tool installed in you space to access this API.
<?xml version="1.0" encoding="UTF-8"?>