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)

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.
* 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.
* tag-field: Tags for the space, comma separated.

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

	    <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 -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: https://www.assembla.com/spaces/<space_id> or https://www.assembla.com/spaces/<space_wiki_name>

Where <space_id> or <space_wiki_name> is the id or wiki_name of the space. 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 -H "Accept: application/xml" http://user:password@www.assembla.com/spaces/c5lQB2YXqr2PaFaaeP0Qfc

or, using space wiki_name instead of space id.

curl -H "Accept: application/xml" http://user:password@www.assembla.com/spaces/space_wiki_name

(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>
	<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> or http://www.assembla.com/spaces/<space_wiki_name>

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

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 -X PUT -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

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.

 COPY SPACE (POST)

 To make a copy of a space, space ID <template_space_id>, from which new space will be copied, should be provided.

 You must send a POST request to http://www.assembla.com/spaces/<template_space_id>/copy_via_api.

 For example. cURL command to invoke the API:

 curl -i -X POST -H "Content-Type:application/xml" -H "Accept: application/xml" -d @<filename>.xml http://login:password@www.assembla.com/spaces/<template_space_id>/copy_via_api

Copy space action contain one more parameter: type, which may take value of "public". e.g "<type>public</type>" for xml or "type=public" for query string

 Note: <filename>.xml should contain valid space data.

 CREATE SPACE(POST)

 To create a space, You should send a POST request to the http://www.assembla.com/spaces/create_via_api

 For example. cURL command to invoke the API:

curl -i -X POST -H "Content-Type:application/xml" -H "Accept: application/xml" -d @<filename>.xml http://login:password@www.assembla.com/spaces/create_via_api

Note: <filename>.xml should contain valid space data.

Delete space API is available only for Assembla Private Installation.

DELETE SPACE(DELETE)

 To delete a space, space ID(<space_id>) should be provided as a parameter. You should send a DELETE request to the http://www.assembla.com/spaces/<space_id>/destroy_via_api

 For example. cURL command to invoke the API

curl -i -X DELETE -H "Content-Type:application/xml" -H "Accept: application/xml" http://login:password@www.assembla.com/spaces/<space_id>/destroy_via_api  

cURL output from create/copy actions.

 Output with successful result should look like:

HTTP/1.1 201 Created

Connection: close

Date: Fri, 30 Jul 2010 10:26:41 GMT

Content-Type: application/xml; charset=utf-8

X-Runtime: 1573

Content-Length: 810

Set-Cookie: _breakout_session=06da75a7781056d1a98df7e803d8037a; path=/; HttpOnly

Cache-Control: no-cache

<?xml version="1.0" encoding="UTF-8"?>

<space>

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

  <created-at type="datetime">2010-07-30T13:26:41+03:00</created-at>

  <default-showpage>Wiki</default-showpage>

  <description>This space was updated from API!</description>

  <id>dXSzc8M8qr37UjacjKAZfO</id>

  <is-commercial type="boolean">true</is-commercial>

  <is-manager type="boolean">true</is-manager>

  <is-volunteer type="boolean">false</is-volunteer>

  <name>s30 (API) update</name>

  <parent-id nil="true"></parent-id>

  <public-permissions type="integer">0</public-permissions>

  <team-permissions type="integer">2</team-permissions>

  <updated-at type="datetime">2010-07-30T13:26:41+03:00</updated-at>

  <watcher-permissions type="integer">1</watcher-permissions>

  <wiki-name>s30_api</wiki-name>

</space>

Output with error messages:

HTTP/1.1 422 

Connection: close

Date: Fri, 30 Jul 2010 10:25:54 GMT

Content-Type: application/xml; charset=utf-8

X-Runtime: 45

Content-Length: 108

Set-Cookie: _breakout_session=72413cb9f1ceb23e9a473e0006d7dd44; path=/; HttpOnly

Cache-Control: no-cache

<?xml version="1.0" encoding="UTF-8"?>

<errors>

  <error>Wiki name has already been taken</error>

</errors>

Output with no access message:

HTTP/1.1 401 Unauthorized

Connection: close

Date: Fri, 30 Jul 2010 10:27:14 GMT

WWW-Authenticate: Basic realm="Web Password"

Content-Type: application/xml; charset=utf-8

X-Runtime: 37

Content-Length: 27

Set-Cookie: _breakout_session=b83d32e4b529d3112b56f6a16d6c57b1; path=/; HttpOnly

Cache-Control: no-cache

HTTP Basic: Access denied.

Result output for delete action

Space successfully deleted

HTTP/1.1 200 OK

Connection: close

Date: Fri, 30 Jul 2010 09:43:55 GMT

ETag: "b36e64ff8a7608d55894d6a46f5cbb52"

Content-Type: application/xml; charset=utf-8

X-Runtime: 33

Content-Length: 98

Set-Cookie: _breakout_session=6912e8a03cc055bce2d7942cb458970b; path=/; HttpOnly

Cache-Control: private, max-age=0, must-revalidate

<?xml version="1.0" encoding="UTF-8"?>

<hash>

  <notice>Space successfully deleted</notice>

</hash>

Space was already been deleted

HTTP/1.1 200 OK

Connection: close

Date: Fri, 30 Jul 2010 09:43:55 GMT

ETag: "b36e64ff8a7608d55894d6a46f5cbb52"

Content-Type: application/xml; charset=utf-8

X-Runtime: 33

Content-Length: 98

Set-Cookie: _breakout_session=6912e8a03cc055bce2d7942cb458970b; path=/; HttpOnly

Cache-Control: private, max-age=0, must-revalidate

<?xml version="1.0" encoding="UTF-8"?>

<hash>

  <notice>Space is already deleted</notice>

</hash>

Space not found

HTTP/1.1 404 Not Found

Connection: close

Date: Fri, 30 Jul 2010 09:44:04 GMT

Content-Type: application/xml; charset=utf-8

X-Runtime: 30

Content-Length: 118

Set-Cookie: _breakout_session=96b190afcdccc2be2ff535ad701e8027; path=/; HttpOnly

Cache-Control: no-cache

<?xml version="1.0" encoding="UTF-8"?>

<hash>

  <error>Can't find space with ID=new_api_milestonefdsf</error>

</hash>

Space tools

Space tools numeric identifiers(tool_id)

Space tools permissions numeric identifiers:

Get space tools

To get the list of tools installed on a space you have to send a GET request to https://www.assembla.com/space/:space_id/tools

An expected body would be:

</spaces-tools>
  <spaces-tool>
    <number type="integer">1</number>
    <created-at type="datetime">2008-04-10T03:00:00+03:00</created-at>
    <watcher-permissions type="integer">0</watcher-permissions>
    <team-permissions type="integer" nil="true"></team-permissions>
    <url nil="true"></url>
    <id>dpyhvYySOr3kWcabIlDkbG</id>
    <package nil="true"></package>
    <tool-id type="integer">14</tool-id>
    <parent-id nil="true"></parent-id>
    <public-permissions type="integer" nil="true"></public-permissions>
    <disk-space type="integer">0</disk-space>
    <name>Time</name>
  </spaces-tool>
  ,,,
</spaces-tools>

cURL example:

curl -i -H "Accept: application/xml" https://user:password@www.assembla.com/spaces/:space_id/tools

Note: for ticket tools you'l get an additional field tool-settings it will contain estimation type of a space if you have estimations enabled for your ticket tool

<tool-settings>
  <estimate-by type="integer">3</estimate-by>
</tool-settings>

Estimate by numeric values described:

Get space repository tools

This query will return only repository tools installed on a space, send a GET request to https://www.assembla.com/spaces/:space_id/tools/repo

cURL example:

curl -i -H "Accept: application/xml" https://user:password@www.assembla.com/spaces/:space_id/tools/repo

Note on repository tools: among with the tool data you will also get a new entity settings

An XML body of a repo tool setting would be

<spaces-tools type="array">
  <spaces-tool>
    ...
    <settings>
      <truncate-to type="integer">10</truncate-to>
      <tickets-url></tickets-url>
      <vcs-url nil="true"></vcs-url>
      <enable-comments-subtab>1</enable-comments-subtab>
      <trigger-url nil="true"></trigger-url>
      <title></title>
      <diff-ignore-spaces nil="true"></diff-ignore-spaces>
      <revprop-hook nil="true"></revprop-hook>
      <state type="symbol">ready</state>
    </settings>
  </spaces-tool>
</spaces-tools>

Body of a repo setting will be different on each tool particularly

Change permissions for space tools

You are able to change permissions of space tools with a request to: https://user:password@www.assembla.com/spaces/test-1/admin/custom_security

To set data send an xml body with your data.

<tools>
  <tool>
    <id>:tool_id</id>
    <watcher_permissions>:permission</watcher_permissions>
    <public_permissions>:permission</public_permissions>
    <team_permissions>:permission</team_permissions>
  </tool>
  <tool>
    ...
  </tool>
  ...
</tools>

To find tools ids and other information send a GET request to https://www.assembla.com/spaces/:space_id/tools.

Add tools to space

You can add any tool from list to your space by send a POST request to https://www.assembla.com/spaces/:space_id/tools?tool_id=:tool_id

A list of available tools:

cURL example:

curl -X POST -H "Accept: application/xml" -d "tool_id=:tool_id" https://user:password@www.assembla.com/spaces/:space_id/tools

In case of success you should get a notice with a corresponding message.

<messages>
  <notice>Source/Git16 Tool created.</notice>
</messages>

Add users to space

To add users to a space you have to send a POST request to https://www.assembla.com/spaces/:space_id/add_members

cURL example:

curl -H "Accept: application/xml" -H "Content-type: application/xml" -d @file.xml https://super:super@www.assembla.com/spaces/:space_id/add_members

Where file.xml contains

<space>
  <users>
    <user>user_login|user@email.com|user_id</user>
  </users>
</space>

An expected result should be an xml body with an array of errors or notices

Remove users from space

To remove users from a space you have to send a POST request to https://www.assembla.com/spaces/:space_id/remove_members

cURL example:

curl -H "Accept: application/xml" -H "Content-type: application/xml" -d @file.xml https://super:super@www.assembla.com/spaces/:space_id/remove_members

Where file.xml contains

<space>
  <users>
    <user>test_3</user>
  </users>
</space>

An expected result should be an xml body with an array of errors or notices