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

• Space Rest API
  • Space XML Representation
  • My Spaces List (GET)
  • My Tool Spaces List (GET)
  • Show space (GET)
  • Update space (PUT)

SPACE REST API

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

In which types can you retrieved the information?

Currently, HTML or XML. HTML is what you have already seen in our site. 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?

SPACE XML REPRESENTATION

<space> 	
   <atributte>Value</atributte>


</space>

REQUIRED ATTRIBUTES (can't be blank)

* name: Name of your space
* wiki-name: Unique URL name.
* wiki-format (type="integer"): Wiki's markup format to create nicely formatted wiki pages.
* team-permissions (type="integer"): Level of access for teams to the space.
* public-permissions (type="integer"): Level of access for non-member users to the space.

OTHER ATTRIBUTES

* description: Short description of the space that appears in search results and tag results.
* moderated (type="boolean"): If true, pwner must approve flow items before they are displayed
* can-join (type="boolean"): If true, any user can join and any member can invite new members.
* default-showpage: Default landing tab of the space.

READ-ONLY ATTRIBUTES (can't be modified)

* id: Unique identifier of the space. You may use this value or the wiki-name for the space routes.
* created-at (type="datetime"): Date and time when the space was created.
* updated-at (type="datetime"): Date and time when the space was last updated
* parent-id: Id of the manager space for this space (if any)
* is-volunteer (type="boolean"): If true, space is marked as volunteer
* is-commercial(type="boolean"): If true, space has a commercial subscription
* is-manager(type="boolean"): If true, space has a manager subscription

MY SPACES LIST(GET)

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

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_spaces

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

<spaces>
	<space>
		<can-join type="boolean">false</can-join>
    	

    	<created-at type="datetime">2007-10-22T10:26:42-03:00</created-at>
	    <default-showpage>Wiki</default-showpage>
	    <description>Assembla Space</description>
	    <id>c5lQB2YXqr2PaFaaeP0Qfc</id>
	    

	    <is-commercial type="boolean">true</is-commercial>
	    <is-manager type="boolean">true</is-manager>
	    <is-volunteer type="boolean">false</is-volunteer>
	    <moderated type="boolean">true</moderated>
	    

	    <name>Assembla</name>
	    <parent-id></parent-id>
	    <public-permissions type="integer">0</public-permissions>
	    <team-permissions type="integer">2</team-permissions>
	    

	    <updated-at type="datetime">2007-12-10T13:01:31-03:00</updated-at>
	    <wiki-format type="integer">2</wiki-format>
	    <wiki-name>assembla</wiki-name>
	</space>

</spaces>

MY TOOL SPACES LIST(GET)

To access the list of the your spaces that has a specific tool installed you need to send a GET request to: http://www.assembla.com/spaces/my_tool_spaces/<tool_id>

Where <tool_id> is one of the followings:

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 and you want to get all your spaces with the Ticket Tool installed, you will write:

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

(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 with the same format as MY SPACES LIST(GET)

SHOW SPACE (GET)

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

Where <space_id> is the id of the space. 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/c5lQB2YXqr2PaFaaeP0Qfc

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

<space>
	<can-join type="boolean">false</can-join>
   <created-at type="datetime">2007-10-22T10:26:42-03:00</created-at>
	<default-showpage>Wiki</default-showpage>
	

	<description>Assembla Space</description>
	<id>c5lQB2YXqr2PaFaaeP0Qfc</id>
	<is-commercial type="boolean">true</is-commercial>
	<is-manager type="boolean">true</is-manager>
	

	<is-volunteer type="boolean">false</is-volunteer>
	<moderated type="boolean">true</moderated>
	<name>Assembla</name>
	<parent-id></parent-id>
	

	<public-permissions type="integer">0</public-permissions>
	<team-permissions type="integer">2</team-permissions>
	<updated-at type="datetime">2007-12-10T13:01:31-03:00</updated-at>
	<wiki-format type="integer">2</wiki-format>
	

	<wiki-name>assembla</wiki-name>
</space>

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

UPDATE SPACE (PUT)

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

Where <space_id> is the id of the space you want to update.

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

Example XML Request with curl:

curl -i -X POSTPUT -H "Content-Type:application/xml" -H "Accept: application/xml" -d "<space><description>Take this description</description></space>" http://user:password@www.assembla.com/spaces/c5lQB2YXqr2PaFaaeP0Qfc

Example POSTForm Request with curl:

curl -i -X POST -H "Content-Type:application/xml"PUT -H "Accept: application/xml" -d "space[description]=Take this description" http://user:password@www.assembla.com/spaces/c5lQB2YXqr2PaFaaeP0Qfc

RESPONSE:

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