In the previous tutorial we've shown the different uses of the "link" object. In this tutorial, we will use the PHP client that was introduced in tutorial 2 to show you how to handle this object. We'll also learn how to retrieve partial responses. The complete source code for this tutorial is also part of the client download package. You can try running it yourself, after having edited the named constants on top of the script. For more information on using the PHP client, see tutorial 2.

This tutorial assumes that a directory named "tutorial6" has already been created on the CDN and 15 files have been uploaded to this directory (named "test1.mp4", "test2.mp4" ...). The sample script uses a local file, which path needs to be set in the named constant 'LOCAL_FILE' in order to create these files.

Getting entry links

You can use the properties of an entry object (= in this case returned by RASS as a response to a PUT item request) to directly access each link element and its attributes. The following code loops through all 'link' elements that are part of the entry and displays the relevant attributes.

  foreach($item->entry->link as $link) {
    echo "\nType of relation: " . $link->rel;
    echo "\nLink URI: " . $link->href;
    echo "\nExpected type: " . $link->type . "\n";
  }

The $rass object also has helper methods which you can use to retrieve the 'href' value of a link with a given relation type. Since this entry is returned by the RASS item resource, it will contain an enclosure link that points to CDN location at which the file (attached to this resource) can be downloaded by end-users.

  echo "\nGetting enclosure link via helper method: " . $rass->getEnclosureLink($item) . "\n";
  >> http://monty.cdn03.rambla.be/tutorial6/test15.mp4

Getting feed links

In the same way as for an entry, you can use a feed object's properties (or helper methods) to directly access each link element and its attributes. The following code loops through all 'link' objects that are part of the feed and displays the relevant attributes.

  foreach($dir_list->feed->link as $link) {
    echo "\nType of relation: " . $link->rel;
    echo "\nLink URI: " . $link->href;
    echo "\nExpected type: " . $link->type . "\n";
  }

Using pagination

In the previous tutorial, we already learned how the 'link' element is being used by some RAWS resources to return partial collections. These resources will return a feed that may contain a 'link' object with its 'rel' attribute set to "next", to indicate that not all entries could be fitted inside of the response. The next page can then be retrieved by sending a GET request to the URI inside of the link element's 'href' attribute.

Most resources that support pagination also return a 'last' link that points to a URL that can be used to retrieve the last batch of entries from a given collection. You can use the $rass object's helper methods getNextLink() and getLastLink() to retrieve these URLs.

For this tutorial we have created a directory that contains 15 files. By passing the 'paginate_by' as part of the query-string arguments (for details, see the 'pagination' wiki page) and setting it to "10", we instruct RASS to return only 10 entries in each (partial) response. Therefore, the response should also contain a 'next' link that points to an URI that can be used to retrieve the 5 remaining entries.

  $dir_list = $rass->getDirList($dir->entry->content->params->path, "kind=file;paginate_by=10");

  echo "\nNext link URI: " . $rass->getNextLink($dir_list) . "\n";
  >> Next link URI: http://rass.cdn03.rambla.be/dir/tutorial6/?kind=file;page=2;paginate_by=10;
  echo "Last link URI: " . $rass->getLastLink($dir_list) . "\n";
  >> Last link URI: http://rass.cdn03.rambla.be/dir/tutorial6/?kind=file;page=2;paginate_by=10;

Note that in this case the 'next' and 'last' link both point to the same URL. This is normal, since RASS only needs to return 5 item entries in its next response. If instead our 'tutorial6' directory would contain more than 20 files, the 'next' and 'last' link would point to different URLs.

The connection object also has two helper methods - getNextList() and getLastList() - that automatically return the $feed object for the 'next' or 'last' link (by sending a GET request to the URL inside their 'href' attribute). When calling these methods, you need to pass the original $feed object as their argument.

   $next_list = $rass->getNextList($dir_list);

Pagination best practices

If you're using a RAWS resource that supports pagination and you want to retrieve all entries from a given collection, you should check for the presence of a 'next' link inside the feed object. You can automate this behaviour by nesting a call to the connection object's getNextList() inside a while-loop that checks on the feed object returned by this call. If there's no 'next' link present (= no more entries), the variable will be set to null and your code will exit the loop.

  $dir_list = $rass->getDirList($dir->entry->content->params->path, 'kind=file;paginate_by=10');
  while($dir_list)
  {
    foreach ($dir_list->feed->entry as $entry) {
      echo "\nFound entry with path = " . $entry->content->params->path;
    }
    $dir_list = $rass->getNextList($dir_list);
  }

In the previous tutorial, we learned how to retrieve ATOM collections from RAWS. More specifically, we retrieved information about our files and directories on the CDN using the RASS API's dir resource. This time, we will repeat these requests using the PHP client from tutorial 2.

The complete source code for this tutorial is also part of the client download package. You can try running it yourself, after having edited the named constants on top of the script. For more information about using the PHP client, see tutorial 2.

Pre-configuration

This tutorial assumes that some files and directories have already been created on the CDN for user 'monty'. The sample script uses a local file (-> path needs to be set in the named constant 'LOCAL_FILE') to create the files.

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

Get files list

First we'll retrieve a list of all files inside our root-directory, by sending a GET request to "http://rass.cdn01.rambla.be/dir/?kind=file;alt=json". To do this, we create a Rass connection object and call getDirList() on it, passing "/" as the first argument. As the second argument, we pass a query-string with the 'kind' argument set to "file".

Query-string arguments are used by RAWS to further specify a request. Depending on the resource, they can be used as a search query, a resource filter, a response format indicator...

If the request succeeds, our method will return a RASS dir feed object. Otherwise, it will raise an exception.

require_once 'raws_json/rass_service.php';
$dir_feed = $rass->getDirList("/", "kind=file");

The returned $feed object contains a list of entry objects which provide information about our files.

foreach($dir_feed->feed->entry as $entry) {
    echo "\nFound " . $entry->content->params->kind . " entry with path = " . $entry->content->params->path . "\n";
    echo "Filename: " . $entry->content->params->filename . "\n";
    echo "Filesize: " . $entry->content->params->size . "\n";
    echo "Download URL: " . $rass->getEnclosureLink($entry) . "\n";
}

>> Found file entry with path = /test1.mp4
>> Filename: test1.mp4
>> Filesize: 13827
>> Download URL: http://monty.cdn01.rambla.be/test1.mp4
>>
>> Found file entry with path = /test2.mp4
>> ...

Get files list for sub-directory

To get the list of files stored under our 'bucks' sub-directory, we only need to change the first getDirFeed() parameter from "/" to "/bucks". The client will now send a GET request to 'http://rass.cdn01.rambla.be/dir/bucks/?kind=file;alt=json'.

$dir_feed = $rass->getDirList("/bucks", "kind=file");
foreach ($dir_feed->feed->entry as $entry) {
    echo "\nFound " . $entry->content->params->kind . " entry with path = " .$entry->content->params->path . "\n";
}
>> Found file entry with path = /bucks/bunny1.mp4
>> Found file entry with path = /bucks/bunny2.mp4

Get list of sub-directories

In this case, we simply set the 'kind' argument to "dir". This will result in a GET request to "http://rass.cdn01.rambla.be/dir/?kind=dir;alt=json".

$dir_feed = $rass->getDirList("/", "kind=dir");
foreach ($dir_feed->feed->entry as $entry) {
    echo "\nFound " . $entry->content->params->kind . " entry with path = " . $entry->content->params->path . "\n";
}
>> Found dir entry with path = /bucks