FLVio MediaKit - API Reference

Overview

This document describes the FLVio MediaKit API. MediaKit provides a RESTful API, exposing access to media resources using existing open standards such as HTTP and XHTML.

A RESTful API is one that follows the principles outlined by the REST (Representational State Transfer) principles of software architecture. REST was introduced in 2000 in the doctoral dissertation of Roy Fielding, one of the principal authors of the HTTP specification. Its principles describe remote access of resources between networked applications using standard HTTP, without adding an RPC layer on top of it such as SOAP.

A RESTful API was chosen because its principles align with the resource-oriented nature of what the project wants to expose. It also allows client-side applications to be very easily created in any programming language that contains an HTTP client library (i.e. almost all of them).

And understanding of RESTful principles is useful, but not necessary, to use the API. A handy resource, for those interested in more information, is the O'Reilly book RESTful Web Services.

Media Items and Media Assets

MediaKit allows users to store and manage multiple "Media Items". A Media Item is representation of a media file, uploaded by the user, which is referenced by a user-supplied identifier (the "id").

Media Items are created by uploading a media file and specifying an ID that does not already exist. The uploaded file is stored as the "original" media file and is never modified. It can be retrieved by the API, but cannot be downloaded by the public.

When a media file is uploaded, MediaKit will automatically encode some files based on the uploaded file. These encoded files are called the "Media Assets" of the Media Item. Each Media Item will contain one or more Media Assets, referenced by asset names.

For example, by default, MediaKit produces two Media Assets per media item: "flv" and "thumb". The "flv" asset is a copy of the original media file re-encoded as a Flash Video (FLV) file. The "thumb" asset is a JPEG image snapshot of the first frame of the video. It is also possible to produce a "h264" asset, which is a copy of the original video file encoded with H.264 for better quality playback by modern Flash video players.

Media Assets can be served to the Internet by using a publicly- accessible URI, and are used for embedding media in public web applications and web sites.

API URI

The RESTful API URI will be prefixed with:: https://mediakit.flvio.com/api/v1/

API commands are specified using the format:

METHOD uri_prefix/resource

Where "METHOD" is a HTTP method (e.g. "GET", "PUT"); "uri_prefix" is the URI specified above; and "resource" is the rest of the URI specifying the resource to access. For example:

GET https://mediakit.flvio.com/api/v1/media

All API requests are authenticated. Authentication credentials link each API request with a specific customer. API requests that do not include authentication details will be rejected. Incorrect authentication details will result in an error. See Authentication.

Responses

Response entity-bodies will contain either:

Nothing: i.e. will be empty;
XHTML document: a representation of a resource;
Binary data: an actual media file (the "Content-Type" header will define the media type).

XHTML encoded responses are not designed to be displayed in a browser (although doing so is useful when debugging) but are designed to be easy to parse, being a common well-known format. Libraries for parsing XHTML should be available for most programming languages, and XML parsing libraries can always be used instead.

All responses will return an HTTP response code as appropriate. Success is always a 2xx code (for example, "200 OK").

Response codes that may be returned by any of the API calls are:

200 ("OK") - the request was successful (some API calls may return 201 instead).
201 ("Created") - the request was successful and a resource was created as a result of it.
204 ("No Content") - the request was successful but there is no representation to return (i.e. the response is empty).
400 ("Bad Request") - the request could not be understood or was missing required parameters.
401 ("Unauthorized") - authentication failed or was not included with the request.
403 ("Forbidden") - the account was denied access (typically, a Free Trial account has expired).
404 ("Not Found") - resource not found (or not yet available, in the case of encoded media assets).
405 ("Method Not Allowed") - resource doesn’t support the requested method.
415 ("Unsupported Media Type") - the media type of the request body was not supported.

Any other standard HTTP status codes may also be returned by the web server. The error will usually not be specific to the MediaKit.

Exceptions or special-case response codes are listed with each API call below.

Media ID

Each media item is referenced by an identifier (ID) that the client defines. When a media file is uploaded to FLVio the client specifies the resource URI to represent the media item. The resource URI ends in an ID that is specified by the user. For example:

https://mediakit.flvio.com/api/v1/media/123

The ID for this media resource is "123".

ID values are limited to 128 characters in length and must be made up of alphanumeric, '-', '_', or '.' characters only.

Media IDs are typically references that make sense to the client. Some examples might be: a reference to a Primary Key in a Videos table of a database; a GUID generated per video; or an MD5 hash of the video's content. Media IDs are specific to each FLVio account.

API Commands

Get list of media

GET uri_prefix/media

Example:

GET https://mediakit.flvio.com/api/v1/media

Request body: empty.

Response:

Response codes:

200 ("OK")
others as per above

Response body: XHTML.

Example XHTML response:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
    "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head><title>Media</title></head>
<body>
 <div id="username">customer1</div>
 <ul id="media">
  <li class="mediaitem" id="mediaitem_1234">
   <a class="apiurl" href="media/1234">API URL</a>
   <a class="asseturl" href="media/1234/assets">Assets</a>
   <dl class="details">
    <dt>id</dt> <dd>1234</dd>
   </dl>
  </li>
  <li class="mediaitem" id="mediaitem_5555">
   <a class="apiurl" href="media/5555">API URL</a>
   <a class="asseturl" href="media/5555/assets">Assets</a>
   <dl class="details">
    <dt>id</dt> <dd>5555</dd>
   </dl>
  </li>
 </ul>
</body>
</html>

Create/update media item (upload/replace media file)

PUT uri_prefix/media/{id}

Example:

PUT https://mediakit.flvio.com/api/v1/media/123

This command either creates or updates a media item by uploading a media file to be re-encoded. If no media item already exists with the specified id then the item is created. If a media item already exists then the corresponding media file is replaced with the uploaded file and all assets are re-created.

The value of id is specified by the client. See Media ID.

When creating a new media item, if the media file is uploaded successfully then it will be added to a queue for processing and the caller will receive a 201 ("Created") response. The media item will now exist, however no encoded assets will exist until the queued item has been processed. The media item is processed asynchronously. For the client to find out when the media item is ready for serving to the Internet (or has failed the encoding process) the client can request the status by fetching the media metadata using the API call below (Fetch media metadata). The X-Flvio-Status header indicates the state of the media item. See Media Item Status Codes for more details.

When used on an existing media item, the item is updated with the values supplied by any request headers (if any). Only values that are to be changed need to be included in the request headers. If the media file itself is to be replaced, it can be included in the body of the PUT request. In this case, any existing encoded assets will be deleted and the newly uploaded file will be queued for processing to produce new assets.

Two request headers ("X-Flvio-Encodeparam-Boxwidth", "X-Flvio-Encodeparam-Boxheight") specify the new dimensions that the video should fit into, with the original aspect ratio kept intact. So if a (wide) video is 640x200, and the parameters are specified as (Boxwidth=320, Boxheight=400) then the video will be resized to 320x100 (i.e. the largest it can be while still fitting into the box 320x400 and without changing the aspect ratio).

By default, MediaKit encodes two assets for a new media item: "flv" and "thumb". The "flv" asset is a copy of the original media file re-encoded as a Flash Video (FLV) file. The "thumb" asset is a JPEG image snapshot of the first frame of the video.

A third asset type is available called "h264", which produces a H.264 encoded copy of the original video that is compatible with Flash player (Flash versions newer than 9.0.115). H.264 encoding produces higher quality video with smaller file sizes than FLV. Hence you will be able to serve higher quality video while using less bandwidth. The catch is that the end user must have a version of Flash newer than 9.0.115 installed. A common workaround is for Flash video players to use the H.264 video if the version of Flash supports it, otherwise fallback to using the FLV format. MediaKit supports encoding both types of video to make this easy.

The assets to be encoded can be specified by customising the "targets". The "thumb" asset is always produced, but to customise the video assets use the "X-Flvio-Targets" header. For example:

X-Flvio-Targets: flv,h264

This example will request both "flv" and "h264" assets to be produced. By default, only "flv" assets are produced (as well as "thumb" which is always created).

Request:

Request body: must not be empty if the media item is being created.: If not empty then the contents must be the media file as binary data.

Request headers:

"X-Flvio-Published" - must contain either "true" or "false", indicating the published state of the item.
"X-Flvio-Filename" - specify the filename of the uploaded file. This is optional but highly recommended, as it helps the video transcoder determine the correct format of the file.
"X-Flvio-Encodeparam-Boxwidth" - width of the box to fit the video into by resizing it without changing the aspect ratio.
"X-Flvio-Encodeparam-Boxheight" - height of the box to fit the video into by resizing it without changing the aspect ratio.
"X-Flvio-Targets" - comma-separated list of asset names to encode. The current list of possible asset names are:
- flv - Flash FLV video (file.flv)
- h264 - Flash-compatible H.264 video (file.mp4)
Note that the "thumb" asset is always produced. Default is "flv".
"X-Flvio-Target-h264-bitrate" - specify the bitrate of the H.264 video. Defaults to "384k".
"X-Flvio-Target-flv-bitrate" - specify the bitrate of the FLV video. Defaults to "512k".
"X-Flvio-Collection" - specify a collection name to assign the media item to. See Collections. Defaults to "" (no collection).

Response:

Response codes:

201 ("Created") - if a new media item was successfully created.
204 ("No Content") - if the existing media item was successfully updated.
400 ("Bad Request") - not enough information to create a new resource.
others as per above

Response headers of interest:

"Location" - contains the URI of the newly created item (i.e. should be same as request URI).

Response body: empty.

Fetch media metadata

HEAD uri_prefix/media/{id}

Example:

HEAD https://mediakit.flvio.com/api/v1/media/123

Used to fetch information about a media item. The information is available whether or not the media item has been processed to produce encoded assets. This request can be used to determine whether a recently uploaded media item has been processed and is ready for serving to the Internet.

Request body: must be empty.

Response:

Response codes:

200 ("OK")
others as per above

Response headers of interest:

"Content-Type" - the mime type of the media item
"X-Flvio-Status" - a string representing the status of the media item, see Media Item Status Codes.
"X-Flvio-Published" - contains either "true" or "false" indicating the published state of the item.
"X-Flvio-Collection" - the collection name the media item is assigned to or empty if not assigned.

Response body: empty.

Fetch original media file

GET uri_prefix/media/{id}

Example:

GET https://mediakit.flvio.com/api/v1/media/123

This request returns the media file as originally uploaded by the client (i.e. the file that the media assets are generated from). It also returns information about the media item, such as the status and published flags.

Request body: must be empty.

Response:

Response codes:

200 ("OK")
others as per above

Response headers of interest:

"Content-Type" - the mime type of the media item
"X-Flvio-Status" - a string representing the status of the media item, see Media Item Status Codes.
"X-Flvio-Published" - contains either "true" or "false" indicating the published state of the item
"X-Flvio-Collection" - the collection name the media item is assigned to or empty if not assigned.

Response body: contains the binary file.

Fetch encoded asset information

GET uri_prefix/media/{id}/assets

Example:

GET https://mediakit.flvio.com/api/v1/media/123/assets

This request returns information about the encoded assets of a particular media item. These are the encoded assets that can be served to the public, such as Flash FLV videos. This information is only available if the media item has been successfully processed (i.e. if the status is "ready").

Request body: must be empty.

Response:

Response codes:

200 ("OK")
404 ("Not Found") - if the media item has not been processed, or if the processing failed (i.e. no encoded assets could be produced)
others as per above

Response headers of interest: none

Response body: XHTML.

Example XHTML response:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head><title>Assets</title></head>
<body>
 <div id="username">customer1</div>
 <div id="mediaid">123</div>
 <div id="collection"></div>
 <ul id="assets">
  <li class="asset" id="asset_thumb">
   <a class="serveurl" href="http://media.serve.flvio.com/media/mediakit/thumb/customer1/123.jpg">Public URL</a>
   <dl class="details">
    <dt>name</dt> <dd>thumb</dd>
    <dt>type</dt> <dd>image</dd>
    <dt>extension</dt> <dd>jpg</dd>
    <dt>contenttype</dt> <dd>image/jpeg</dd>
   </dl>
  </li><li class="asset" id="asset_flv">
   <a class="serveurl" href="http://media.serve.flvio.com/media/mediakit/flv/customer1/123.flv">Public URL</a>
   <dl class="details">
    <dt>name</dt> <dd>flv</dd>
    <dt>type</dt> <dd>video</dd>
    <dt>extension</dt> <dd>flv</dd>
    <dt>contenttype</dt> <dd>video/x-FLV</dd>
   </dl>
  </li>
 </ul>
</body>
</html>

Delete media item

DELETE uri_prefix/media/{id}

Example:

DELETE https://mediakit.flvio.com/api/v1/media/123

This request permanently deletes a media item and all related encoded assets.

Request body: must be empty.

Response:

Response codes:

204 ("No Content") - the resource deletion was successful.
others as per above

Response headers of interest: None

Response body: empty.

Options

OPTIONS uri_prefix/{path}

Example:

OPTIONS https://mediakit.flvio.com/api/v1/media/123

The OPTIONS method is a standard HTTP method to request a list of methods supported by the specified URI. The method can be used on any resource URI to reveal the supported methods.

Request body: must be empty.

Response:

Response codes:

200 ("OK")
others as per above

Response headers of interest:

"Allow" - contains the HTTP methods allowed for the requested URI, separated by commas. For example "GET,HEAD,PUT".

Response body: empty.

Media Item Status Codes

The following are the possible values of a media item status code (i.e. the "X-Flvio-Status" header):

"queued" - the media item is still queued for processing;
"ready" - the media item has been successfully processed to produce media assets;
"failed" - processing of the media item failed, no assets were produced.

URIs for Encoded Assets

The public URIs for encoded assets are constructed differently to the API URIs. These URIs are not actually part of the API, but are public facing for accessing the encoded assets from client web applications. The representation returned by the Fetch encoded asset information API contains absolute links to each asset.

URIs are of the form:

GET http://media.serve.flvio.com/media/mediakit/{asset name}/{username}/{id}.{extension}

Examples:

GET http://media.serve.flvio.com/media/mediakit/flv/customer1/1234.flv
GET http://media.serve.flvio.com/media/mediakit/image/customer1/1234.jpg

Note that encoded assets can only be accessed if the media item published flag is "true". Otherwise a 404 is returned.

Authentication

HTTP Basic Auth is used for client authentication. Clients must include an "Authorization" header with every request, containing the authentication credentials. The response will fail with a 401 ("Unauthorized") if the "Authorization" header is not included or if the authentication credentials are incorrect.

Collections

Media items can be grouped together in what FLVio calls "collections". Collection names don't need to be created in advance of assigning media to them. There are no separate API calls to manage collections, but the media item list can be filtered by collection name. A media item can only belong to one collection at a time and does not need to be assigned to any collection (the default).

Specify the collection to assign the video to as part of the Create/update media item (upload/replace media file) (PUT) request by specifying the "X-Flvio-Collection" header. For example:

X-Flvio-Collection: foo

to assign a media item to the collection named "foo". Any previous assignment would be replaced.

An empty value will clear the collection assignment from a media item.

Collection names are limited to 64 characters in length and must be made up of alphanumeric, '-', '_', or '.' characters only.

The media list representation will contain a "collection" definition for media items that are assigned to a collection. For example:

<li class="mediaitem" id="mediaitem_foobar">
 <a class="apiurl" href="media/foobar">API URL</a>
 <a class="asseturl" href="media/foobar/assets">Assets</a>

 <dl class="details">
  <dt>id</dt> <dd>foobar</dd>
  <dt>collection</dt> <dd>test1</dd>
 </dl>
</li>

The response to a Media item GET or HEAD request will contain an "X-Flvio-Collection" header specifying the collection name or an empty value if not assigned to a collection (the default).

The media list (https://mediakit.flvio.com/api/v1/media) representation will list all media items from all collections by default. An optional query parameter "collection" can be used to filter the media list by collection. Specify a collection name to filter by collection or an empty value to filter by media items not assigned to any collection. Examples:

https://mediakit.flvio.com/api/v1/media?collection=test1

https://mediakit.flvio.com/api/v1/media?collection=

The media assets representation will contain the collection name and include the collection name as part of the public URL (see below).

Collection names will be added as part of the media serve URL. With no collection assigned, an example media URL would be:

http://media.serve.flvio.com/media/mediakit/flv/customer/123.flv

When assigned to a collection "foobar" the same media item would instead have a URL of:

http://media.serve.flvio.com/media/mediakit/flv/customer/foobar/123.flv

Updated:	2009-01-15
Version:	1.3.0
Copyright:	Locayta LTD 2008. All rights reserved.