RATS REST API
This API describes the manner in which the RAmbla Transcoding Service (aka RATS) can be addressed. For general information about Rambla Web Services and how to access them, first learn the RAWS API Basics.
Contents |
Resources
Overview
- user : user account information and user-specific settings
- input : Profile containing information about the transcoding source file (= input) location.
- output : Profile containing information about the destination(s) at which the transcoded file (= output) should be published.
- format : Profile describing the transcoding format.
- job : Transcoding action to be done on a given source file, according to the settings in a given format profile.
- src : Source file located on the server, which can be bound to a transcoding job.
- overlay : Overlay file to be referenced in a transcoding format (e.g. for adding a watermark to a transcoded file)
- transc : Transcoded file, as the result of a certain job, which is (temporarily) available on the RATS server.
- srcencode : Allows a user to let his end-users directly upload files, and get them automatically transcoded and published.
You can also retrieve the Service Document for the RATS API by sending a GET request to http://rats.enc01.rambla.be/?alt=atom. Service Documents enable the discovery of the capabilities and locations of the different resources, grouped in collections.
See Also
- RATS Common Query-String Arguments : query-string arguments that can be used for some or all resources
- RATS job report : the report that is created after completion of a transcoding job
- Sending batch jobs with RATS : batch processing (e.g. for adaptive streaming) + info about the CDN report
- RATS Custom Processing Actions : additional actions which may take place while a job is being processed
- RATS Source Formats : guidelines for source files
- RAWS Documentation : documentation overview
Profile Resources
The input, output and format resource act as profiles. They each describe a particular stage of the RATS job request:
- format profile : Describes how RATS needs to transform the source file into a transcoded file. A job request always requires a reference to an existing format profile.
- input profile : Describes how RATS needs to import the source file (if it has not been previously uploaded). If the source file has already been uploaded to the RATS server, no input profile is needed.
- output profile : Describes how RATS needs to export the transcoded file to an external location. An output profile is optional. As an alternative, you can choose to download the transcoded file from the RATS server (via the transc resource).
As a first step, you create a profile by giving it a name and setting its properties (usually through the RATS web-interface). When created, the profile gets a numerical ID that will remain unchanged during the complete lifetime of the profile. You can edit the contents of an existing profile, as long as no pending jobs are using it. Profiles will only cease to exist when you delete them.
To use a profile, you pass along the ID in the dedicated parameter of a job request, thereby determining how RATS will process the job. Once created, a profile can be re-used in any number of job requests.
Default Profiles
Default profiles are created by Rambla and are available to all RATS users. They can not be modified or deleted.
Even though default profiles do not show up in the regular profile lists, they can be used in the same way as your own profiles. You simply pass the profile ID in the dedicated parameter of the job request. To get back default profiles in your profile lists, use the 'owner' query-string argument. For example, http://rats.enc01.rambla.be/format/?owner=sys will retrieve the list of default format profiles.
Remarks
- Input/Output Profiles : For security reasons, authentication credentials are currently not transmitted as part of a RATS request/response. If you create an input or output profile that requires authentication, just provide us with the credentials and we will store them as part of your profile.
- Format Profiles : The specifications of some of the multi-media containers and codecs may require specific settings to be present in your transcoding format. If you have trouble transcoding to a certain format, contact support@rambla.be.
Characters and Syntax
RATS resources contain different kinds of properties, so which characters are allowed largely depends on the kind of property. The general rule here is "be sensible"; use only those characters that should be part of the property that you are setting. For example: when passing a parameter that expects (part of) a URI, use the characters and syntax described in rfc3986.
Since RATS must be able to format its data as an XML response, 'free-text parameters' (e.g. 'title', 'description', 'client_passthru') should preferably not include characters reserved by XML (<,>,',",&). If you do so, RATS will replace these characters by their character codes when sending a response or formatting a job report. As of version 1.40, RATS also supports unicode for 'free-text parameters', encoded as 'utf-8'.
Methods and URIs
The base URI for RATS resource access is http://rats.enc01.rambla.be.
Here is an overview of the operations that are supported on the different types of resources.
| URI | GET | POST | PUT | DELETE |
|---|---|---|---|---|
| /user/{username} | Get account info and settings | Overwrite writable data | ||
| /input | List available input profiles | Create a new input profile | ||
| /input/{id} | View an existing input profile | Overwrite the profile | Overwrite the profile | Delete the profile |
| /output | List available output profiles | Create a new output profile | ||
| /output/{id} | View an existing output profile | Overwrite the profile | Overwrite the profile | Delete the profile |
| /format | List available format profiles | Create a new format profile | ||
| /format/{id} | View an existing format profile | Overwrite the profile | Overwrite the profile | Delete the profile |
| /job | List transcoding jobs | Create a new transcoding job | ||
| /job/{id} | View an existing job | Delete the job | ||
| /src | List transcoding source files | Upload a new source file | Upload a new source file | |
| /src/{username}/{filename} | Get metadata for a source file | Delete a source file | ||
| /overlay | List overlay files | Upload a new overlay file | ||
| /overlay/{id} | Get metadata for overlay | Update metadata for overlay | Delete overlay (file + metadata) | |
| /overlay/media/{id} | Download an overlay file | |||
| /transc | List transcoded files | |||
| /transc/{username}/{filename} | Get metadata for a transcoded file | Delete a transcoded file | ||
| /transc/media/{username}/{filename} | Download a transcoded file | |||
| /srcencode/ | HTTP hotfolder mechanism |
RATS Administration
Browser Access
RATS can also be accessed using a browser: this provides the user with an interface for monitoring programmatic access, doing non-repetitive tasks (e.g. creating transcoding formats) or testing.
The manner in which resources are accessed is basically the same for programmatic access and web-browser access. All resource URI's should produce the same results in the browser, only with the response being formatted as an HTML page. Tip: add "alt=atom" or "alt=xml" to the URI's query-string to display the browser response in an alternate format.
Apart from the resource URI's, some browser specific pages have been added to the RATS site for convenience purposes (e.g. overview page).
Source Upload via FTP
It is possible to upload your source files to RATS using FTP. The RATS FTP server name is ftp.enc01.rambla.be (ftp://ftp.enc01.rambla.be) and credentials are the same as those of your RATS account. Note that you must have requested RATS FTP access explicitly, in order to gain access to ftp.enc01.rambla.be. To do this, just contact support@rambla.be.
A file that has been uploaded to ftp.enc01.rambla.be will be automatically moved to your RATS upload directory and attached to a newly created RATS src instance. This also means that you won't be able to access the uploaded file using your ftp client, once the upload has completed.
If the name of the uploaded file is in accordance with the Rambla filesystem conventions and it is unique (= you don't already have a RATS src with this filename), then it will be retained by RATS. Otherwise RATS will rename the file (by replacing invalid characters and/or adding a numerical suffix) before creating the src instance. You can verify the URI and filename of this new resource by looking it up in the src list (GET http://rats.enc01.rambla.be/src).
Data Transmission Formats
For more details about (explicitly) specifying a format, see the RAWS API Basics page. We recommend the use of the Atom Publishing Protocol as a request format and Atom as a response format. Form-encoding is supported for browsing, but not separately documented and tested for programmatic interaction.
Request Formats
A request to RATS must be sent over HTTP. If data is present in the request body, the mimetype that is described in the Content-Type Header should be one of the following:
- application/x-www-form-urlencoded or, in case of a file upload, multipart/form-data. See the W3C HTML form content types for details.
- application/atom+xml;type=entry, for the Atom Publishing Protocol (APP)
- binary data, in case the request body contains the contents of a media file.
Response Formats
Currently, RATS supports these response formats:
- Atom Syndication Format
- HTML pages and forms
