This is the first of a series of tutorials that will help you get to grips with Rambla Web Services. In this tutorial, we will use the cURL command-line tool to communicate with Rambla Storage Service (RASS). We will demonstrate how to use RASS for file- and directory management on our CDN and, in the meantime, show the basic mechanics of a REST API and the Atom Publishing Protocol.

If you are not familiar with the concept of REST or the Atom Publishing protocol (= atompub), you can find a detailed explanation on our wiki as well as some examples. The atompub specification (= rfc 5023) itself is also a very readable introduction to both REST and atompub. Or you could watch these videos by Google's Joe Gregorio: 'Intro to the Atom Publishing Protocol' and 'Intro to REST'.

In this tutorial, you will learn how to create a directory, upload files, and delete files and directories using the RASS API. For these purposes, RASS exposes the "dir" and "item" resources. Additionally, RASS also exposes a "meta" resource that allows you to retrieve, manage or search for metadata. We will look at these metadata features in another tutorial.

Create Directory

So let's get started. First, we'll create a new directory named "tutorial1" inside the account of a user named "monty" on CDN03. We can do this by sending an HTTP POST request to the "dir" resource and passing the name for our new directory in the URL path: "http://rass.cdn03.rambla.be/dir/tutorial1/".

In cURL syntax, this translates to: "curl --url http://rass.cdn03.rambla.be/dir/tutorial1/ --request POST --user monty:mypwd", which produces the following output (only relevant lines are included here):

curl --url http://rass.cdn01.rambla.be/dir/tutorial1/ --request POST --user monty:mypwd --verbose

> POST /dir/tutorial1/ HTTP/1.1
> Authorization: Basic bW9udHk6bXlwd2Q=
> Host: rass.cdn03.rambla.be

< HTTP/1.1 201 Created
< Content-Length: 923
< Location: http://rass.cdn03.rambla.be/dir/tutorial1/
< Content-Type: application/atom+xml;type=entry

<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xmlns:raws="http://rambla.be/raws/ns-metadata/1.0" raws:kind="dir" 
  raws:path="/tutorial1">
  <id>http://rass.cdn03.rambla.be/dir/tutorial1/</id>
  <title>/tutorial1</title>
  <updated>2010-06-18T13:21:44+02:00</updated>
  <author>
    <name>monty</name>
  </author>
  <link href="http://rass.cdn03.rambla.be/dir/tutorial1/?;kind=root,file,dir" rel="self" type="application/atom+xml"/>
  <link href="http://rass.cdn03.rambla.be/dir/tutorial1/" rel="edit" type="application/atom+xml"/>
  <link href="http://rass.cdn03.rambla.be/dir/tutorial1/?alt=html;;kind=root,file,dir" rel="alternate" 
    type="application/atom+xml"/>
  <summary>4096 bytes, updated on 2010-06-18 13:21:44</summary>
  <content type="application/xml">
    <params xmlns="http://rambla.be/raws/ns-metadata/1.0">
      <name>tutorial1</name>
      <size>4096</size>
      <updated>2010-06-18 13:21:44</updated>
    </params>
  </content>
</entry>

In the HTTP response body, RASS returns an ATOM entry which contains all information about the directory that has just been created. The entry element's "raws:path" attribute contains the directory's relative path on the CDN. The entry's "atom:content" element contains the RAWS-specific information in the form of an xml structure which is contained inside the "raws:params" element. The actual parameters for each resource are defined in the Rambla wiki.

Upload File

To upload a file to the CDN, you insert its contents as the binary body of a HTTP POST request to the RASS item resource. The URL path (= "/tutorial1/") should point to the directory in which RASS needs to store the uploaded file. The SLUG HTTP header (= defined by the atompub protocol) must be present to suggest a filename to RASS.

curl --url http://rass.cdn03.rambla.be/item/tutorial1/ --user monty:mypwd --data-binary @./recordings/taste.mp4 
      -H "SLUG: cookbook.mp4" --verbose

> POST /item/tutorial1/ HTTP/1.1
> Authorization: Basic bW9udHk6bXlwd2Q=
> Host: rass.cdn03.rambla.be
> SLUG: cookbook.mp4
> Content-Length: 239136

< HTTP/1.1 201 Created
< Date: Fri, 18 Jun 2010 12:06:37 GMT
< Content-Length: 1102
< Location: http://rass.cdn03.rambla.be/item/tutorial1/cookbook.mp4/
< Content-Type: application/atom+xml;type=entry

<?xml version="1.0"?>
<entry xmlns="http://www.w3.org/2005/Atom" xmlns:raws="http://rambla.be/raws/ns-metadata/1.0" 
  raws:kind="file" raws:path="/tutorial1/cookbook.mp4">
  <id>http://rass.cdn03.rambla.be/item/tutorial1/cookbook.mp4/</id>
  <title>/tutorial1/cookbook.mp4</title>
  <updated>2010-06-18T14:06:39+02:00</updated>
  <author>
    <name>monty</name>
  </author>
  <link href="http://rass.cdn03.rambla.be/meta/monty/tutorial1/cookbook.mp4/" rel="self" 
    type="application/atom+xml"/>
  <link href="http://rass.cdn03.rambla.be/item/tutorial1/cookbook.mp4/" rel="edit" type="video/mp4"/>
  <link href="http://monty.cdn03.rambla.be/tutorial1/cookbook.mp4" rel="enclosure" type="video/mp4"/>
  <summary>239136 bytes, updated on 2010-06-18 14:06:39</summary>
  <content type="application/xml">
    <params xmlns="http://rambla.be/raws/ns-metadata/1.0">
      <name>cookbook.mp4</name>
      <size>239136</size>
      <updated>2010-06-18 14:06:39</updated>
      <mimetype>video/mp4</mimetype>
    </params>
  </content>
</entry>

The "Location" header (= see also the entry's editable "link" element) points to the item resource that RASS has just created. In doing this, RASS has made your file publicly available on the CDN at "http://monty.cdn03.rambla.be/tutorial1/cookbook.mp4", as specified by the enclosure URL. Finally, the entry's self "link" element points to a URL that you can use to retrieve or attach metadata for/to this new resource.

Unless you are using globally unique filenames, you should always check the HTTP response to get the actual filename given by RASS. For instance, when you issue the same command for a second time, RASS will respond with the following "Location" header and ATOM entry.

< Location: http://rass.cdn03.rambla.be/item/tutorial1/cookbook000.mp4/

<entry raws:kind="file" raws:path="/tutorial1/cookbook000.mp4" xmlns="http://www.w3.org/2005/Atom" 
  xmlns:raws="http://rambla.be/raws/ns-metadata/1.0">
  <link href="http://monty.cdn03.rambla.be/tutorial1/cookbook000.mp4" rel="enclosure" type="video/mp4" />
...
</entry>

Since a file named "cookbook.mp4" already exists, RASS adds a numerical suffix to the filename suggested in the SLUG header.

Delete File

To delete the file we've just created, we can send an HTTP DELETE request to the "item" resource, passing the relative path (= "tutorial1/cookbook000.mp4") to the file that needs to be deleted.

curl --url http://rass.cdn03.rambla.be/item/tutorial1/cookbook000.mp4 --request DELETE 
       --user monty:mypwd --verbose 

> DELETE /item/tutorial1/cookbook000.mp4 HTTP/1.1
> Authorization: Basic bW9udHk6bXlwd2Q=
> Host: rass.cdn03.rambla.be
 
< HTTP/1.1 204 No Content
< Content-Length: 0

To confirm that the file has been deleted, RASS sends back a response with status code "204 No Content" and an empty body.

Delete Directory

In the same way, a directory can be deleted by sending an HTTP DELETE request to the "dir" resource, and passing the directory's relative path in the URL. But since our "tutorial1" directory still contains a file, a non-recursive delete attempt will fail.

curl --url http://rass.cdn03.rambla.be/dir/tutorial1/ --request DELETE --user monty:mypwd --verbose

> DELETE /dir/tutorial1/ HTTP/1.1
> Authorization: Basic bW9udHk6bXlwd2Q=
> Host: rass.cdn03.rambla.be
 
< HTTP/1.1 403 Forbidden
< Content-Length: 283
< Content-Type: application/xml

<?xml version="1.0" encoding="utf-8"?>
<error xmlns="http://rambla.be/raws/ns-metadata/1.0">
  <code>ResourceCanNotBeDeleted</code>
  <message>You are not allowed to delete this resource.</message>
  <reason>The directory you tried to delete (path = /tutorial1) is not empty.</reason>
</error>

RASS returns a response with status code "403 Forbidden" and an XML-formatted error message in the body. However, we can recursively delete the directory by passing "recursive=1" as part of the URL's query-string arguments.

curl --url http://rass.cdn03.rambla.be/dir/tutorial1/?recursive=1 --request DELETE --user monty:mypwd --verbose

> DELETE /dir/tutorial1/?recursive=1 HTTP/1.1
> Authorization: Basic bW9udHk6bXlwd2Q=
> Host: rass.cdn03.rambla.be
 
< HTTP/1.1 204 No Content
< Content-Length: 0

In this case, RASS responds with status code "204 No Content" to confirm that the directory has indeed been deleted.

Laila came into this world on April 4th in animal park Planckendael. She is the first snow leopard to be born in Belgium. And the cub definitely has some star-quality! You can see for yourself at the Planckendael site.