RAWS - API Basics

From Rambla Wiki
Jump to: navigation, search

HTTP Requests and Responses

All APIs are based on REST methodology and support the JSON data format. By default, a RAWS request requires HTTP Basic Authentication. Authentication credentials are the username and password of your Rambla account.

Requests

All requests should contain following headers:

  • Authorization : should contain the user's credentials (username and password of your Rambla user account) in Basic Authentication format. If authentication fails, RAWS will return a "401 UNAUTHORIZED" response.
  • Content-Type : should be set to "application/json", unless a file is being uploaded (in which case it should be set to the file's mimetype, e.g. "video/*").
  • Accept : should always be set to "application/json".
  • Content Length : should always contain the number of bytes in the request body.

If the request body contains binary data (file upload), the request should also contain the following header:

  • Slug : suggested filename (in accordance with Rambla's filename conventions) for the uploaded file. Note that RAWS may choose to alter this when creating the resource instance (e.g. when a file with the given name already exists). The client application should therefore always check the response to find out the correct filename.

Unless a file is being uploaded, the request body should be valid JSON.

Responses

A successful RAWS request results in a response with one of the HTTP success status codes:

  • "200 OK" : Default.
  • "201 Created" : In case a (POST or PUT) request was sent in order to create a new resource instance, the success code will be "201 Created". In this case, you should check the Location header of the response for the URI of the new resource instance.
  • "204 No Content" : Will be returned after a successful DELETE request, indicating that all content at the request URI has been removed. In this case, the response body will always be empty.

Unless a file is being transferred, the response body will be encoded in JSON (if the request's Accept header has been set to "application/json").

In case of failure, RAWS will return a error response with a status code in the 400 or 500 range. The body of the error response is a JSON object that consists the following key/value pairs:

  • code : short, textual description of the error (e.g. "NoSuchResource")
  • message : human readable text (e.g. "The specified resource does not exist.")
  • reasons (optional, depending on the error) : list of further details about the error (e.g ["Resource doesn't exist (path = /my_deleted_resource)"])

Data Transfer

The request/response body will contain either an entry or a feed object (in json format). A single resource instance corresponds to an entry object, a list of resource instances to a feed object.

The basic structure of an entry object looks like this:

{
  "entry": {
    "content": {
      "params": {
        "param1": "value1",
        "param2": "value2",
        ...
      }
    }
  }
}

The json 'entry' object has a 'content' member, which contains a 'params' object with the actual resource properties (= key/value pairs) as described in the reference pages. When sending a RAWS request, it suffices to provide this basic structure in the request body (containing all required params for the resource). In the response, the 'entry' will contain some additional datamembers which further describe the resource instance.

A json 'feed' object is basically a list of entries. Apart from the 'entry' member, the 'feed' object also contains some extra information.

{
  "feed": {
    "entry": [...],
    ...
  }
}

For more details, see the entry and feed reference pages.

Create or update request

You create a resource instance by sending a POST or PUT request. For most resources, the body of this request will be an entry object.

For example, this request launches a transcoding job by sending a POST request to the RATS job resource.

> POST /job/ HTTP/1.1
> Host: rats.enc01.rambla.be
> Authorization: Basic ZGFmZnk6c2VjZXJldA==
> Content-Type: application/json
> Accept: application/json
> Content-Length: 5064

{
  "entry": {
    "content": {
      "params": {
        "src_location": "my_home_movie.avi",
        "format": "163",
        "output": "1",
        "tgt_location": "test/movie1"
      }
    }
  }
}

If the job instance was successfully created, RATS sends back a HTTP 201 response containing a job entry. The response contains the URI at which the job progress can be monitored. This URI can be retrieved from the 'Location' Header or from the 'id' property of the entry object. The params object contains a new 'status' property in which the status of this job is returned. If the job is part of a batch, the 'batch_status' property will contain a value between 0 and 100 (indicating batch progress).

< HTTP/1.1 201 Created
< Content-Length: 5426
< Content-Type: application/json
< Location: http://rats.enc01.rambla.be/job/4562811/

{
  "entry": 
  {
    "id": "http://rats.enc01.rambla.be/job/4562811/",
    "content": {
      "params": {
        "src_location": "my_home_movie.avi",
        "format": "163",
        "output": "1",
        "tgt_location": "test/movie1",
        "id": "4562811",
        "status": "1",
        "batch_status": "-1"
      }
   }
}

Get entry or feed

By sending a GET request to a resource you can retrieve either a single instance (entry) or a list of instances (feed).

  • To retrieve a single instance, send your request to the location of that instance. For example, a GET request to http://rats.enc01.rambla.be/job/4562811/ will return the entry for that job instance.
  • To retrieve a list of instances, send your request to the resource URL. For example, a GET request to http://rats.enc01.rambla.be/job/ will return a feed object, contain entries for all available job instances. By using query-string arguments, you can filter the entries that will be returned. For example, to retrieve a list of all transcoding jobs which are currently pending, send a GET request to http://rats.enc01.rambla.be/job/?status=busy.

File Upload

Some resources are created by uploading a file. To upload a file, send a POST or PUT request containing the (binary) file as its body. Unless specified otherwise, the request should contain a Slug header which contains a proposed filename to be used by RAWS.

The following example uploads a file, to be used for transcoding, to the RATS src resource:

> POST /src/ HTTP/1.1
> Host: rats.enc01.rambla.be
> Authorization: Basic ZGFmZnk6c2VjZXJldA==
> Content-Type: video/mpeg
> Slug: my_home_movie.mpg
> Accept: application/json
> Content-Length: 4438602

...binary data... 

RAWS responds with a HTTP 201 CREATED response, containing an entry that describes the instance that has been created. Note that RAWS may change the filename you provided in the 'Slug' header (e.g. add a suffix to it, if a file with the same name already exists). Therefore, you should check the 'filename' param in the response (if your client code depends on it).

< HTTP/1.1 201 Created
< Content-Length: 2048
< Location: http://rats.enc01.rambla.be/src/monty/my_home_movie.mpg/
< Content-Type: application/json

{
  "entry": {
    "id": "https://rats.enc01.rambla.be/src/monty/my_home_movie.mpg/",
    "content": {
      "params": {
         "filename": "my_home_movie.mpg",
         "updated": "2012-06-05 09:25:49",
         ...
      }
    }
  }
}