RASS dir resource
Contents |
Actions Overview
The RASS dir resource allows a user to manage directories on the Rambla CDN.
- GET http://rass.{cdn0x}.rambla.be/dir/[{dirname}/...]/
- PUT http://rass.{cdn0x}.rambla.be/dir/[{dirname}/...]/
- POST http://rass.{cdn0x}.rambla.be/dir/[{dirname}/...]/
- DELETE http://rass.{cdn0x}.rambla.be/dir/[{dirname}/...]/
The URI http://rass.{cdn0x}.rambla.be/dir/ points to the home directory for the given user-account on the CDN. Additionally the relative path may be appended to a sub-directory the user is trying is to access.
GET request
Retrieves information about a certain directory's contents.
Query String Arguments
Announcement: pagination in RASS v4 !!
- For performance reasons, RASS v4 will limit the number of entries that can be retrieved in a single request. To retrieve an unlimited number of results, a client should use pagination. See the pagination section below for details.
kind
When retrieving (GET) a directory's contents, the query-string may contain the kind argument to indicate which kind of content the resulting feed may contain. Possible values: "root", "dir" or "file". Multiple "kind" arguments may be combined in a single request (e.g. kind=file,dir).
- kind=root : only retrieve the (summary) information for the root-directory itself (= the directory specified in the path).
- kind=dir : only retrieve the information for the root-dir's sub-directories
- kind=file : only retrieve the information for the files located inside the root-dir
- kind=all : (= default) => same as kind=root,dir,file
name
The name argument allows you to search for files and/or directories whose names correspond to a certain pattern, by using the question mark operator or star operator as wildcards. To be part of the query-string, both operators need to be URL encoded.
- ? (%3F) : wildcard for a single character
- * (%2A) : wildcard for multiple characters
Examples:
- http://rass.cdn03.rambla.be/dir/movies/?name=tutorial%2A : returns all files and directories (inside the user account's 'movies' directory) whose names start with 'tutorial' (e.g. "tutorial22", "tutorial.mp4")
- http://rass.cdn03.rambla.be/dir/?name=t%3Fp.mp4 : will return "tip.mp4" and "top.mp4", but NOT "turnip.mp4"
The 'name' argument may not be combined with the 'tag' and 'meta' arguments. The 'tag' and 'meta' arguments will be ignored if the 'name' argument is present in the query-string.
pagination
A traffic feed may contain partial results, if more entries are available than the number of entries per page. The default number of entries per page is 50, but the client can tweak this number by including the paginate_by argument in the query-string. The maximum number of entries per page is 100. For more details about pagination in general, see the ATOM pagination reference.
Note: for backward compatibility, pagination is currently still omitted (= all results are returned in a single response) when a request is made in accordance with the RAMS v2 API. To get ready for RAMS v4, client application maintainers should adapt their "traffic" requests, so they contain a 'paginate_by' argument in the query-string. In RAMS v4, all requests without a 'paginate_by' argument will default to ("?paginate_by=50").
Partial results are ordered first according to the kind of entry and second alphabetically.
- If the "root" entry (= summary) is being requested, it will be returned in every page and not be counted as a separate entry.
- If both files and directories are being requested, RASS will first return all available files in alphabetic order (= path). After all file entries have been returned, RASS will start returning the directory entries in alphabetic order.
Response
The dir resource responds to a GET request with an atom (or xml) feed (see RAWS Atom Response Format for the general structure). Depending on the kind argument in the query-string, the response may contain the following entries:
- an entry (raws:kind = root) that represents the root-directory
- a separate entry (raws:kind = dir) for each sub-directory, located directly beneath the root-directory
- a separate entry (raws:kind = file) for each file, located directly beneath the root-directory
Entry attributes
To further specify its contents, each 'entry' element will contain two additional attributes:
- raws:kind = the kind of the entry. Possible values are root, dir and file.
- raws:path = the complete relative path of this dir/item on the Rambla CDN, starting from the user's root-directory.
Params Elements
The raws:params element inside each entry's content element contains the following elements:
- raws:name : the file or directory-name
- raws:size : the size in bytes of the file or directory (recursive)
- raws:updated : the date at which the file was stored or the directory was created
Common Errors
A request to the RASS dir resource succeeds if the URI path points to an existing directory under the user's root-directory on the CDN.
- In case the directory doesn't exist, RASS will reply with a NoSuchResource RAWS Error Code.
PUT request
Creates a new directory at the specified location on the Rambla CDN. The name of the directory to be created should be the last part of the path. This directory should not already exists.
For example: PUT http://rass.cdn01.rambla.be/dir/Simpsons/Movies/ will attempt to create a Movies sub-directory under the Simpsons directory. If the Simpsons directory (located directly under the user's root-directory) doesn't exist, it will be created as well.
Response
When successful, the response will have a HTTP status code of 201. The response HTTP headers will also contain a Location Header, which specifies the RASS URI at which this new resource instance can be reached.
Common Errors
- ResourceAlreadyExists (409 CONFLICT), in case a dir or item with the same name already exists at the given location.
See RAWS Error Codes for more details.
POST request
Creates a new directory at the specified location on the Rambla CDN. The difference with "PUT dir" is that, when using POST, RASS will also create a new resource if a directory with the same name already exists. The name of the directory, passed in the last part of the URL path, may thus be modified by appending a numerical suffix at the end of it. The caller should check the response message, to retrieve the actual name that was given to the directory.
For example: POST http://rass.cdn01.rambla.be/dir/Simpsons/Movies/ will attempt to create a Movies sub-directory under the Simpsons directory. If such directory already exists, RASS will create a directory anyway, naming it "Movies000".
Response
When successful, the response will have a HTTP status code of 201. The response HTTP headers will also contain a Location Header, which specifies the RASS URI at which this new resource instance can be reached. In the body, the actual name of the directory is returned inside the raws:name param (see the GET request section for details).
DELETE request
Deletes a directory at the specified location on the Rambla CDN. The name of the directory to be deleted should be the last part of the path.
Query-String Arguments
recursive
By default, RASS requires that the directory must be empty before it can be deleted. If you try to delete a non-empty directory, a '403 FORBIDDEN' error will be returned. However, you can recursively delete an existing directory by including the query-string argument recursive with its value set to "1".
For example:
- DELETE http://rass.cdn01.rambla.be/dir/Simpsons/Movies/ will attempt to delete a Movies sub-directory under the Simpsons directory. The Movies directory should be empty.
- DELETE http://rass.cdn01.rambla.be/dir/Simpsons/Movies/?recursive=1 will attempt to recursively delete a Movies sub-directory under the Simpsons directory. All files and directories inside the Movies directory will be deleted.
Response
When successful, the response will have a HTTP status code of 204 and no body.
Common Errors
- NoSuchResource (404 NOT FOUND), in case the directory doesn't exist.
- ResourceCanNotBeDeleted (403 FORBIDDEN), in case the directory is not empty.
See RAWS Error Codes for more details.
