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
Documents are our resources here which can be referred to using this global identifier (URI):
http://www.assembla.com/spaces/<space_id>/documents/
Where <space_id> is the id of the space 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 space File tab. 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?
<document> <atributte>Value</atributte> </document>
REQUIRED ATTRIBUTES (can't be blank)
* name: User's name of the file
OTHER ATTRIBUTES (modifiable)
* description: Description of the document
* attachable-id: Id of the object associated with this document
* attachable-type: Type of the object associated with the document. Can be Flow or Ticket.
* use-as (type="boolean"): Set to true if you want to use this image in the ImageTool (works only for image type documents).
* position (type="integer"): Order of the document in the Image Tool list
* created-at (type="datetime"): Date and time when the file was uploaded. Automatically filled, but you can change it when creating a document. You are not allowed to when updating it's attributes.
* created-by: Id of the user who uploaded the file. Automatically filled with your user, but you can change it when creating a document. You are not allowed to when updating it's attributes.
* skip_alerts (type="boolean"): Default: false. Set it to true if you want to avoid generating alerts when a document 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 document among all spaces. You will need this value for the document routes.
* space-id: Id of the space the document belongs to.
* filename: System file name.
* content-type: Content-type of the document.
* version (type="integer"): Version of the file.
* updated-at (type="datetime"): Date and time of the last change.
* updated-by: Id of the user who last uploaded any attribute.
To access the list of your documents you need to send a GET request to: http://www.assembla.com/spaces/<space_id>/documents/
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/documents
(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:
<documents> <document> <attachable-id>1</attachable-id> <attachable-type>Ticket</attachable-type> <content-type>image/jpeg</content-type> <created-at type="datetime">2007-12-20T15:34:35-03:00</created-at> <created-by>user_id</created-by> <description> </description> <filename>Image.jpg</filename> <filesize type="integer">354222</filesize> <id>a2W8IaRYOr3jE_abNrdR7q</id> <image-filename></image-filename> <indexable-text></indexable-text> <name>MyImage</name> <position type="integer">0</position> <space-id>my_space_id</space-id> <updated-at type="datetime">2007-12-20T15:34:35-03:00</updated-at> <updated-by>user_id</updated-by> <use-as type="boolean"></use-as> <version type="integer">1</version> </document> </documents>
To create a new document you need to send a POST request to: http://www.assembla.com/spaces/<space_id>/documents/
You need to send the new document information in the request body with multipart/form-data Content-Type, file field should be named document[file]
If you want to get the response in xml format, be sure to include "Accept:application/xml" in your request header.
Form Example
<form action="www.assembla.com/spaces/unfuddle/documents" enctype="multipart/form-data" method="post"> <input id="document_file" name="document[file]" size="30" type="file" /> <input id="document_name" name="document[name]" size="30" type="text" value="" /> </form>
Example Form Request with curl:
curl -i -X POST -H "Accept: application/xml" -F "document[name]=My Test File" -F "document[file]=@filename" http://user:password@www.assembla.com/spaces/my_space_id/documents
RESPONSE:
If you success on creating the document you will get a Response with 201 Status and with the new document xml representation. If the creation fails you will get a 422 Status and an xml representation of the errors. Eg:
<errors> <error>name - A file already exists with the name you specified.</error> </errors>
To access the representation of a simple document you need to send a GET request to: http://www.assembla.com/spaces/<space_id>/documents/<document_id>
Where <document_id> is the id of the document 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/documents/a2W8IaRYOr3jE_abNrdR7q
(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 document:
<document> <attachable-id>1</attachable-id> <attachable-type>Ticket</attachable-type> <content-type>image/jpeg</content-type> <created-at type="datetime">2007-12-20T15:34:35-03:00</created-at> <created-by>user_id</created-by> <description> </description> <filename>Image.jpg</filename> <filesize type="integer">354222</filesize> <id>a2W8IaRYOr3jE_abNrdR7q</id> <image-filename></image-filename> <indexable-text></indexable-text> <name>MyImage</name> <position type="integer">0</position> <space-id>my_space_id</space-id> <updated-at type="datetime">2007-12-20T15:34:35-03:00</updated-at> <updated-by>user_id</updated-by> <use-as type="boolean"></use-as> <version type="integer">1</version> </document>
In case the document does not exist you will get a Not Found 404 Status in the response
To download document binary data you need to send a GET request to: http://www.assembla.com/spaces/<space_id>/documents/<document_id>/download
Where <document_id> is the id of the document you are trying to download that belongs to the space with <space_id>
To update a simple document you need to send a PUT request to: http://www.assembla.com/spaces/<space_id>/documents/<document_id>
Where <document_id> is the id of the document 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 document information, send it in the body as it is explained in the CREATE DOCUMENT (POST) section.
You can send the new document information in the request body in two ways: Submitting a form with post method and rails convention for names OR with an XML (send XML in the request body and set Content-Type to application/xml).:
Example XML Request with curl:
curl -i -X PUT -H "Content-Type:application/xml" -H "Accept: application/xml" -d "<document><name>New Name</name></document>" http://user:password@www.assembla.com/spaces/my_space_id/documents/a2W8IaRYOr3jE_abNrdR7q
Example Form Request with curl:
curl -i -X PUT -H "Accept: application/xml" -d "document[name]=New Name" http://user:password@www.assembla.com/spaces/my_space_id/documents/a2W8IaRYOr3jE_abNrdR7q
RESPONSE:
If you success on updating the document you will get a Response with 200 Status and with the new document xml representation. If the update fails you will get a 422 Status and an xml representation of the errors.
To delete a simple document you need to send a DELETE request to: http://www.assembla.com/spaces/<space_id>/documents/<document_id>
Where <document_id> is the id of the document you are trying to delete that belongs to the space with <space_id>
Example XML Request with curl:
curl -i -X DELETE -H "Accept: application/xml" http://user:password@www.assembla.com/spaces/my_space_id/documents/a2W8IaRYOr3jE_abNrdR7q
I am using the example syntax for uploading a file but am not sure what I am doing wrong.
Here's the syntax I'm using (from the command line).
"C:\Program Files\cUrl\curl.exe" -i -X POST -H "Accept: application/xml" -F "document[name]=MyDocument.doc" -F "document[file]=D:\PathTo\MyDocument.doc" http://MyUserName:MyPassword@www.assembla.com/spaces/MySpaceNamedocuments
The API creates a file but with the content being only the string "MyDocument.doc". I'm assuming that I did something wrong, and I haven't been able to find an example of how to do a multi-part HTTP POST using curl.exe outside of this document. I thought that the @filename was just an example placeholder but it apparently has some more meaning.