RAWS tutorial 3 : getting collections

In this third episode of our RAWS tutorial series, we will show you how to retrieve a collection of resources. We'll also explain how to tweak RAWS requests using query-string arguments. To demonstrate some of the REST mechanics involved, we will be using the cURL command line tool. In our next tutorial, we will show you how to make the same requests using the PHP client libraries.

Most RAWS resources are able to return a collection of resources in response to a GET request, in the form of an ATOM feed. The RASS API's dir resource returns a feed if the URL path part (after the resource indicator 'dir') points to a directory on the CDN. This feed contains information about files, sub-directories and/or the directory itself, depending on the arguments passed in the query-string part of the GET request.

To demonstrate this, some files and directories have been created on the CDN for user 'monty':

• Files located under the root-directory: test1.mp4, test2.mp4.
• Files located under a 'bucks' sub-directory: bunny1.mp4, bunny2.mp4.

Get files LIST

We'll start this tutorial by sending a 'GET dir' request for our root directory in order to retrieve the files it contains: "http://rass.cdn01.rambla.be/dir/?kind=file".

• The path part of the URL is set to "/dir/". Since the resource indicator is only followed by a slash, the GET request is pointed at the root-directory.
• The query-string contains a kind argument which is set to "file", indicating that we only want to receive entries that reference files.

The (relevant) output from curl looks like this:

curl --url http://rass.cdn01.rambla.be/dir/?kind=file --request GET --user monty:mypwd --verbose
> GET /dir/?kind=file HTTP/1.1
> Host: rass.cdn01.rambla.be

< HTTP/1.1 200 OK
< Content-Type: application/atom+xml

<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:raws="http://rambla.be/raws/ns-metadata/1.0">
  <id>http://rass.cdn01.rambla.be/dir/?kind=file;page=1;paginate_by=100</id>
  <link href="http://rass.cdn01.rambla.be/dir/?kind=file;page=1;paginate_by=100" rel="self" type="application/atom+xml"/>
  <entry raws:kind="file" raws:path="/test1.mp4">
    <id>http://rass.cdn01.rambla.be/item/test1.mp4/</id>
    <link href="http://rass.cdn01.rambla.be/meta/monty/test1.mp4/" rel="self" type="application/atom+xml"/>
    <link href="http://rass.cdn01.rambla.be/item/test1.mp4/" rel="edit" type="video/mp4"/>
    <link href="http://monty.cdn01.rambla.be/test1.mp4" rel="enclosure" type="video/mp4"/>
    <content type="application/xml">
      <params xmlns="http://rambla.be/raws/ns-metadata/1.0">
        <name>test1.mp4</name>
        <size>13827</size>
        <updated>2010-11-18 09:35:45</updated>
        <mimetype>video/mp4</mimetype>
      </params>
    </content>
  </entry>
  <entry raws:kind="file" raws:path="/test2.mp4">
    <id>http://rass.cdn01.rambla.be/item/test2.mp4/</id>
    <link href="http://rass.cdn01.rambla.be/meta/monty/test2.mp4/" rel="self" type="application/atom+xml"/>
    <link href="http://rass.cdn01.rambla.be/item/test2.mp4/" rel="edit" type="video/mp4"/>
    <link href="http://monty.cdn01.rambla.be/test2.mp4" rel="enclosure" type="video/mp4"/>
    <content type="application/xml">
      <params xmlns="http://rambla.be/raws/ns-metadata/1.0">
        <name>test2.mp4</name>
        <size>13827</size>
        <updated>2010-11-18 09:35:45</updated>
        <mimetype>video/mp4</mimetype>
      </params>
    </content>
  </entry>
</feed>

The response body has an atom:feed root-element which is the container for a number of atom:entry sub-elements, each containing information about a file located directly under the root-directory. In this example, the feed contains 2 entries.

Each entry element has an atom:id sub-element, containing the URI at which the corresponding item resource can be accessed. Also note the 'enclosure' link which points to the file's public URL, to be used by end-users for downloading the file from the CDN. The file's properties are inside the raws:params element (sub-element of atom:content).

Get files LIST FOR sub-directory

To get the files that are stored under our 'bucks' sub-directory, we simply have to add this directory to the URL path of our GET request: "http://rass.cdn01.rambla.be/dir/bucks/?kind=file". RASS will now return a feed with 2 entries referencing 'bunny1.mp4' and 'bunny2.mp4'. The feed's atom:id element looks like this:

http://rass.cdn01.rambla.be/dir/bucks/?kind=file;page=1;paginate_by=100

To find out where a file is located, look at the raws:path attribute of the entry element which points to the relative path of the file on the CDN.

<entry raws:kind="file" raws:path="/bucks/bunny1.mp4">

Get LIST OF sub-directories

In our previous requests, we've indicated to RASS that we only want information about files. In the same way, we can retrieve information about sub-directories by setting the 'kind' query-string argument to "dir". The following GET request will return all sub-directories of our CDN root-directory: "http://rass.cdn01.rambla.be/dir/?kind=dir".

<feed xmlns="http://www.w3.org/2005/Atom" xmlns:raws="http://rambla.be/raws/ns-metadata/1.0">
  <id>http://rass.cdn01.rambla.be/dir/?kind=dir;page=1;paginate_by=100</id>
  <entry raws:kind="dir" raws:path="/bucks">
    <id>http://rass.cdn01.rambla.be/dir/bucks/</id>
    <link href="http://rass.cdn01.rambla.be/dir/bucks/?kind=dir" rel="self" type="application/atom+xml"/>
    <link href="http://rass.cdn01.rambla.be/dir/bucks/" rel="edit" type="application/atom+xml"/>
    <summary>31750 bytes, updated on 2010-11-18 09:35:45</summary>
    <content type="application/xml">
      <params xmlns="http://rambla.be/raws/ns-metadata/1.0">
        <name>bucks</name>
        <size>31750</size>
        <updated>2010-11-18 09:35:45</updated>
      </params>
    </content>
  </entry>
</feed>

Since we have only created a single sub-directory named "bucks", RASS returns a feed with a single entry. As you can see, the entry's raws:kind attribute is now set to "dir". The raws:path attribute contains the directory's relative path.