RASS item resource

From Rambla Wiki
Jump to: navigation, search

Contents

Actions Overview

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

  • GET http://rass.{cdn0x}.rambla.be/itemdata/[{dirname}/.../]{itemname}/
  • GET http://rass.{cdn0x}.rambla.be/item/[{dirname}/.../]{itemname}/
  • HEAD http://rass.{cdn0x}.rambla.be/item/[{dirname}/.../]{itemname}/
  • POST http://rass.{cdn0x}.rambla.be/item/[{dirname}/...]/
  • PUT http://rass.{cdn0x}.rambla.be/item/[{dirname}/.../]{itemname}/
  • DELETE http://rass.{cdn0x}.rambla.be/item/[{dirname}/.../]{itemname}/

The URI http://rass.{cdn0x}.rambla.be/item/ must be followed by the relative path to the given media item (= filename, including 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 may point to a file that is located directly under the user's root-directory (e.g. http://rass.cdn01.rambla.be/item/my_video.mp4/).

GET requests

GET item entry 

GET http://rass.{cdn0x}.rambla.be/itemdata/[{dirname}/.../]{itemname}/

Returns an entry containing information about an existing "item" resource. This entry should be the same as the entry returned in response to a POST or PUT item request.

For example, for a user "monty" that has a file named "taste.avi" inside his "/python/movies" directory on cdn01, such entry would look like this (some atom elements omitted for clarity): 

<?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="file" raws:path="/python/movies/taste.avi">
  <id>http://rass.brkdev.rambla.be/item/python/movies/taste.avi/</id>
  <title>/python/movies/taste.avi</title>
  <link href="http://rass.brkdev.rambla.be/itemdata/python/movies/taste.avi/" rel="self" type="application/atom+xml"/>
  <link href="http://rass.brkdev.rambla.be/item/python/movies/taste.avi/" rel="edit" type="video/avi"/>
  <link href="http://rass.brkdev.rambla.be/meta/monty/python/movies/taste.avi/?alt=atom" rel="alternate" type="application/atom+xml"/>
  <link href="http://monty.cdn01.rambla.be/python/movies/taste.avi" rel="enclosure" type="video/avi"/>
  <content type="application/xml">
    <params xmlns="http://rambla.be/raws/ns-metadata/1.0">
      <name>taste.avi</name>
      <size>13827</size>
      <updated>2010-02-01 15:26:38</updated>
      <mimetype>video/avi</mimetype>
    </params>
  </content>
</entry>
  • The "entry" root-element has a raws:path attribute, which contains the path to this file on the CDN.
  • The entry contains different atom:link elements, distinguished by their "rel" (= relationship) attribute:
    • self link : points to the item entry itself
    • edit link : points to an URL at which the item can be edited (eg by sending a DELETE request to this URL) or downloaded from RASS
    • alternate link : points to an URL where the metadata for this entry (if any) can be found
    • enclosure link : points to the location of the file on the CDN
  • The entry contains an 'atom:content' element, which contains the raws:params for this entry:
    • name : filename, including extension
    • size : number of bytes
    • updated : time at which this file was created
    • mimetype : mimetype of the file

GET file 

GET http://rass.{cdn0x}.rambla.be/item/[{dirname}/.../]{itemname}/

Downloads a binary file from the RASS server. Except for cases where the file on the CDN is protected from download, we recommended you to NOT use this method but download the file from its CDN location instead (see the "GET item entry" section on how to retrieve the download link). Downloading files from RASS comes with a performance penalty and is limited to files smaller than 500 Mb.

HEAD request

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

Response

A HEAD response will never contain a body, whether successful or not. In case of success, the response will have a HTTP status code of 200. The response HTTP headers will contain Content-length and Content-type headers, specifying the size in bytes and mimetype of the file.

Common Errors

  • The HTTP status code will be 404 NOT FOUND in case the item doesn't exist.

POST request

Upload a binary file and uses it to create a new item instance at the location on the Rambla CDN which is specified in the path part of the URI. The proposed filename must be passed by setting the request's the Slug HTTP header. The body of the request should contain the complete binary file, without an encoding of any sort.

If the file is successfully uploaded, RASS will always make sure that the file gets created:

  • if a file with the same name already exists, RASS will create a unique filename by appending a numerical suffix to the proposed filename (e.g. "file_exists.mp4" => "file_exists001.mp4")
  • if the file location (as specified in the URI path) doesn't exist, RASS will create the necessary (sub-)directories before storing the file

Note that this behaviour is completely different from the PUT method, which returns an error in both these cases.

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 entry can be reached (= URL for a GET itemdata request). The response body will be the entry containing the filename which was used to store the file.

Note that you should check the filename (= in the response body) of the new item created by a POST request, since RASS may append a numerical suffix to the filename (= if a file with the same name already exists).

PUT request

Uploads a binary file and uses it to create a new item instance at the specified location on the Rambla CDN. The name of the item to be created should be the last part of the URI path and should include an extension. The rest of the path should point to a directory that already exists.

For example: PUT http://rass.cdn01.rambla.be/item/Simpsons/eat_my_shorts.mp4/ will attempt to upload the binary file from the request's body and use it to create a file named eat_my_shorts.mp4 inside the Simpsons directory. The Simpsons directory should be located immediately under the user's root-directory and should already exist.

The body of the request should contain the complete binary file, without an encoding of any sort.

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 (= URL for a GET itemdata request).

Common Errors

  • IncompleteBody (400 BAD REQUEST), in case not all bytes of the binary file were received by RASS.
  • NoSuchResource (404 NOT FOUND), in case the parent-directory doesn't exist.
  • 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.

DELETE request

Deletes an item at the specified location on the Rambla CDN. The name of the item to be deleted should be the last part of the path.

For example: DELETE http://rass.cdn01.rambla.be/item/Simpsons/eat_my_shorts.mp4/ will attempt to delete a file named eat_my_shorts.mp4 which is located in the Simpsons directory.

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 item doesn't exist.

See RAWS Error Codes for more details.

Retrieved from "http://rampubwiki.wiki.rambla.be/index.php?title=RASS_item_resource&oldid=2412"
Personal tools
Namespaces
Variants
Actions
Navigation
Toolbox