RASS item resource

Overview

The RASS item resource allows a user to manage files on the Rambla CDN.

For GET, HEAD and DELETE requests, the URL http://rass.{cdn0x}.rambla.be/item/ must be followed by the relative path to the given file (including filename and extension) on the Rambla CDN. The relative path may include sub-directories (e.g. http://rass.cdn02.rambla.be/item/movies/flash/my_video.flv/) or no directory at all (to select a file located directly under the user's root-directory).

• GET (file info) http://rass.{cdn0x}.rambla.be/itemdata/{relative_path_to_file}/
• GET (file) http://rass.{cdn0x}.rambla.be/item/{relative_path_to_file}/
• HEAD http://rass.{cdn0x}.rambla.be/item/{relative_path_to_file}/
• DELETE http://rass.{cdn0x}.rambla.be/item/{relative_path_to_file}/

For POST and PUT requests, the URL http://rass.{cdn0x}.rambla.be/item/ must be followed by the relative path to a directory on the CDN, in which to publish the uploaded file. In this case, the body of the HTTP requests contains the file's binary data and the (suggested) filename is specified via a custom HTTP header (= 'Slug').

• POST http://rass.{cdn0x}.rambla.be/item/{relative_path_to_parent_directory}/
• PUT http://rass.{cdn0x}.rambla.be/item/{relative_path_to_parent_directory}/

Content

The item response may contain:

• an entry containing the item params, in case of PUT, POST and GET file info requests.
• the file itself (binary data), in case of a GET file request
• an empty body, in case of HEAD and DELETE requests

Params

A file entry contains the following params:

• path : specifies the relative path to the file
• filename : the filename
• size : size of the file or directory (= recursive) in bytes
• mimetype : the file's mimetype (or "unknown")
• kind : specifies the kind of location (e.g. "file")
• name : the filename of the location (included for backward compatibility support, may be removed in feature releases)

GET file info request

GET http://rass.{cdn0x}.rambla.be/itemdata/{relative_path_to_file}/

Returns an entry containing data about an existing "item" resource.

For example, for a user "monty" that has a file named "my_movie.mp4" inside his "/mydir" directory on cdn01, such entry would look like this:

{
    "entry": {
        "id": "http://rass.cdn01.rambla.be/item/mydir/my_movie.mp4/",
        "content": {
            "params": {
                "filename": "my_movie.mp4",
                "path": "/mydir/my_movie.mp4",
                "name": "my_movie.mp4",
                "mimetype": "video/mp4",
                "kind": "file",
                "size": "4438602"
            }
        },
        "updated": "2012-06-07T12:21:47+02:00",
        "link": [{
            "href": "http://rass.cdn01.rambla.be/meta/monty/mydir/my_movie.mp4/?alt=json",
            "type": "application/json",
            "rel": "self"
        },
        {
            "href": "http://monty.cdn01.rambla.be/mydir/my_movie.mp4",
            "type": "video/mp4",
            "rel": "enclosure"
        }]
    },
    "version": "1.0",
    "encoding": "UTF-8"
}

As you can see, the entry contains an enclosure link which points to the URL for downloading this file from the CDN.

GET file request

GET http://rass.{cdn0x}.rambla.be/item/{relative_path_to_file}/

Downloads a binary file from RASS (= requires authentication). This method is included for situations where the file on the CDN is protected from download. In other cases, we strongly recommended you to download the file from the CDN instead. Downloading files from RASS comes with a performance penalty and is limited to files smaller than 500 Mb.

HEAD request

HEAD http://rass.{cdn0x}.rambla.be/item/{relative_path_to_file}/

Retrieves the HTTP Header information about an item resource instance. The HEAD method can be used instead of GET, to find out if a file exists and retrieve its size without having to download the binary file.

When the request is successful, RASS returns a HTTP 200 OK response with an empty body. You should check the following HTTP headers for additional information:

• 'Content-length' : file size in bytes
• 'Content-type' : mimetype of the file.

When the request fails, RASS returns a response with an appropriate HTTP error code and no body.

POST or PUT request

POST/PUT http://rass.{cdn0x}.rambla.be/item/{relative_path_to_parent_directory}/

Publish a new file on the CDN by uploading it to the given parent directory (= part of the URL path). The upload request must contain:

• in the URL, the path to a directory on the CDN (= after the 'item/' specifier). If the directory doesn't exist, RASS will create the necessary (sub-)directories before storing the file.
• a 'Slug' HTTP header with the suggested filename. Note: if a file with the same name already exists, RASS will change the suggested filename by appending a numerical suffix to the end (e.g. "file_exists.mp4" => "file_exists001.mp4").
• in the request body, the file's binary data.

Query-string argument supported by POST/PUT:

• "replace=1" (default = 0) : if 'replace' is set and a file with the given path already exists on the CDN, it will be replaced by the uploaded file (instead of creating the uploaded file with a numerical suffix).

When the request is successful, the response will have a HTTP status code of 201. The response will contain:

• a 'Location' Header, specifying the RASS URL at which this new resource instance can be accessed (= GET file info URL).
• the item entry in the body, which can be used to check the file's relative path (entry->content->params->path) or the full URL (enclosure link) for downloading the file from the CDN.

See also RASS example - publishing files on the CDN.

DELETE request

DELETE http://rass.{cdn0x}.rambla.be/item/{relative_path_to_file}/

Deletes a file at the specified location on the CDN.

When the request is successful, the response will have a HTTP status code of 204 and no body. Otherwise, the response will contain an appropriate HTTP error code.

See also RASS example - publishing files on the CDN#Delete file.