RAWS API Basics
Contents |
Background info: REST and APP
All APIs are based on REST methodology and support the Atom Publication Protocol (= APP), which determines the general request and response formats. This page explains the basic rules for RAWS interaction through either one of these APIs.
REST Mechanics
REST is an acronym that stands for Representational State Transfer. Central to the RESTful way of doing things is the concept of a resource. Each resource that is exposed by a web service, allows the client application to address a specific kind of functionality. All instances of a resource are accessible over HTTP using a global identifier (a URI).
Basically, any type of operation that can be performed using a RAWS Web Service is determined by three different parameters:
- the HTTP method supplies the action that will be taken, when accessing the resource. Possible actions are GET, POST, PUT, DELETE and HEAD. Different resources may allow a different subset of these methods to be used against them.
- GET : retrieve one or more resource instances
- HEAD : only retrieve the HTTP header information for a resource instance
- POST and PUT : create or update a resource instance
- DELETE : delete a resource instance
- the resource indicator determines the kind of resource that the request is accessing (e.g. "job" for a transcoding job). The resource indicator typically is passed as the first part of the request path, directly after the service's base URI.
- the resource identifier identifies the specific resource instance that will be accessed. It consists of the rest of the request path, immediately after the resource indicator. In most cases - but not always - the resource identifier will be absent when creating a new resource instance.
Example:
PUT http://rass.cdn01.rambla.be/dir/my_new_dir/
- The PUT method signifies that we want to create a new resource instance (http://rass.cdn01.rambla.be/" is the base URI for RASS)
- "dir/" is the resource indicator, meaning that we attempt to create a new directory (= instance of the dir resource)
- "my_new_dir/" is the resource identifier, meaning that the directory-name will be "my_new_dir", and that it will be located straight under the user account's root-directory
Depending on the kind of resource, some types of operations may further be defined by:
- the URI's query-string : this may contain arguments that further specify how a certain kind of operation (= HTTP method) should be executed against the instance (= resource identifier) of a certain resource (= resource indicator).
- the request body : this may contain data to be set on the resource instance. See the request section below for more details on how this data should be formatted.
Atom and APP
The Atom Syndication Format is an XML language used for retrieving feeds and other data from a web-server. Atom also provides the Atom Publishing Protocol (APP), an HTTP-based protocol for publishing and editing web resources, which uses Atom feeds and entries as its basic entities for information exchange. Furthermore, the APP protocol also contains an implicit RESTful logic for the description and access of web resources.
All RAWS APIs support Atom and APP as their main request and response formats.
RAWS Interaction: HTTP requests and responses
Requests
Requests are sent using the HTTP protocol, except for browser requests to the RATS or RASE site who are using HTTPS instead (your browser will be redirected to a secure location). For customers or projects that require an additional level of security, HTTPS access for web service clients is possible too (contact Rambla support for more info).
Authentication
By default, a RAWS request requires HTTP Basic Authentication. Authentication credentials are the username and password of your Rambla account. In case authentication fails, the RAWS response will contain "401 UNAUTHORIZED" as its HTTP status code.
HTTP Headers
All RAWS requests should contain the Authorization Header containing the user's credentials in Basic Authentication format (see above). Depending on the type of resource and/or operation, a request may call for certain headers (defined in rfc 2616 or a different protocol) to be present. For example:
- When the request contains a body, the Content-Type Header should indicate the mimetype of the content that is transferred inside the body. Some examples are:
- When posting a new resource instance that has been formatted in accordance with the Atom Publishing Protocol (APP), the 'Content-Type Header' should be set to "application/atom+xml;type=entry".
- When uploading a binary file, the 'Content-Type Header' should be set to the file's mimetype.
- When using the APP protocol to create a new resource instance by uploading a file, the request should contain a Slug Header which specifies the filename that needs to be given to the uploaded file.
- In all cases, the HTTP Accept Header may be used to specify the mimetype of the response format that the client wants to receive. For instance "application/atom+xml" will call for an Atom response.
Request Body
When (meta)data needs to be transferred in the request body, it must be encoded in a format supported by the web service. Currently, all Rambla web services support the Atom Publishing Protocol (APP), which requires the "Content-Type Header" to be set to application/atom+xml;type=entry
In addition, the RAmbla Transcoding Service also supports the request body to be application/x-www-form-urlencoded or, in case of a form that includes file upload, multipart/form-data, for interaction using a browser. See the W3C HTML form content types for details.
Responses
The result of a request is conveyed through standard HTTP header mechanisms. In case of an error response, RAWS returns additional error information in the response body. See RAWS Error Response for more details.
HTTP Status
A RAWS response always returns a status code as prescribed in the HTTP protocol. Please note that some of the possible success codes differ from the standard "200 OK":
- "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, the HTTP Headers will also include a custom "Location" header (see below).
- "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.
See also RAWS Error Response for the status codes that may be expected in case of failure.
HTTP Headers
Some important response headers:
- Content-Type Header : mimetype of the content that is transferred in the response body
- Location Header : in case a new resource has been created, it contains the URI at which the new resource can be accessed.
Response Body
When the service response contains a body, it will be encoded in one of the response formats supported by RAWS.
Specifying the Response Format
A client application can indicate the format of the response that it wants to receive in two ways:
- By specifying one of the supported mimetypes in the request's Accept Header: For example use "Accept: application/atom+xml" to retrieve an ATOM feed.
- By explicitly requesting an alternate format in the query-string part of the URI: e.g. http://rats.enc01.rambla.be/format/?alt=atom.
The response type specified in the URI's query-string part takes precedence over the one in the ACCEPT header. If no response type is specified in the URI and the Accept Header does not exist or doesn't contain an acceptable response type (or contains more than one acceptable response type), the server will choose the Atom format to respond with.
Available Formats
Currently, all Rambla web services support the Atom Syndication Format : set the 'Accept Header' to 'application/atom+xml' or pass 'alt=atom' in the query string.
In addition, the RAmbla Transcoding Service can also send HTML responses : this behaviour can be forced by setting the 'Accept Header' to 'text/html' or by passing 'alt=html' in the query string. Be warned however that this response format serves to make RATS accessible via a browser. It should not be used for programmatic access, since the data markup may be subject to change.
