1. Introduction

This document describes all REST web services offered by MediaMosa to external application developers.

1.1 Objective

This document gives a detailed description of the REST interfaces and can be used as a basis for end user application development. The target group of this document is end user application developers.

1.2 Summary

An application that wishes to use the services of MediaMosa must in the first instance be able to register (authentication), so this is the first section that requires your attention after the introduction. After logging in, an application starts with an empty video database, so a video will have to be uploaded. The easiest thing to do is to implement a POST upload form. After a successful upload, it is possible to ask MediaMosa to play the video (playback chapter). There are different playback request options. Depending on the application to be developed, all media management functions can be studied, or transcoded, for instance.

A reference application written in JAVA with the Liferay framework, which can be used as reference application, forms part of MediaMosa. In a number of places this document has been extended with e.g. a PHP code (e.g. authentication) that can be used.

1.3 Abbreviations

Abbreviation	Meaning
API	Application Programmers Interface
CITE	Continuous Integration and Test Environment
IDE	Integrated Development Environment
DTAP	Develop, Test, Accept, Produce
REST	Representational State Transfer
SOAP	Simple Object Access Protocol
WSDL	Web Service Definition Language

1.4 Changes to REST calls [POST] MediaMosa 1.1.6 and higher

The parameters that have been changed for REST calls using the POST method. It is all backwards compatible, but documentation has been amended. The GET variables used for 1.1.6 with POST REST calls have all been converted to POST. This means that all variables with the POST method must also all be sent via the POST method. user_id in particular used to be a GET parameter in most cases, but in some REST calls was POST.

This has now been corrected; all POST REST calls have POST variables, and all GET REST calls have GET variables. However, all former GET variables in the POST REST call continue to work and are therefore entirely backwards compatible.

2. INTRODUCTION

MediaMosa supplies a scalable and future-proof platform for the storage, maintenance and serving of visual material. In a controlled environment, applications can use a wide range of services, varying from storing, describing, retrieving and playing back videos, to the transcoding of video material to other formats and offering video collections for indexing by advanced OAI harvesters.

MediaMosa is based on Representational State Transfer (REST) architecture: all interactions with the system take place via these REST calls. REST is a variation on the Simple Object Access Protocol (SOAP), where requests to the server are not made in XML format, but in URL format. The server’s replies are always in XML format.

The XML reply is built up as follows:

<?xml version="1.0"?>

<response>

<header>

<item_count>10</item_count>

<item_count_total>23489</item_count_total>

<item_offset/>

<request_process_time>0.1064</request_process_time>

<request_query_count>11</request_query_count>

<request_result>success</request_result>

<request_result_description></request_result_description>

<request_result_id>601</request_result_id>

<request_uri>[GET] asset?limit=10</request_uri>

<vpx_version>1.0.1</vpx_version>

</header>

<items>

<item id="1">

...

</item>

<item id="2">

...

</item>

...

</items>

</response>

Tag	Value	Description
response	n/a	container of the entire XML reply
header	n/a	container of the request information
item_count	numerical	number of items in this reply
item_count_total	numerical	total number of items that meets the request
item_offset	numerical	the offset used
request_process_time	float	the time needed by MediaMosa to formulate the reply
request_result	alpha-numerical	“success” or “error”
request_result_description	string	description that forms part of the result
request_result_id	numerical	the number of the result
request_uri	n/a	[http method] and the request to MediaMosa
vpx_version	version	version number of the MediaMosa platform
items	n/a	container that can be filled with the requested or generated items
item	n/a	this field contains the requested or generated items

MediaMosa offers the following services to the applications.

Media management

• media management (Create, Read, Update, Delete)

• management of Dublin Core metadata for media

• storage of application-specific metadata

• reading technical metadata of media

• protection of video material and metadata

• updating existing media with new media versions

Playback / streaming / download / live stream

• playing back media by means of a playback ticket (film ticket)

• validity checks of tickets

• streamed playback of streamable media

• downloading of media if permitted

• tracing back playback requests to a live stream

Searching

• making indexing collections available to OAI-PMH harvester

• finding media by means of search commands

Authorisation & Authentication

• challenge / response authentication on an application level

• authorisation on a collection, asset, media and metadata level

• authorisation on a web service level

Transcoding

• transcoding of media to and from common formats: MPEG1/2, H.264, VC-1, WMV1/2, Flash video, QuickTime etc.

• possibility to use a standard format option

• possibility for automatic transcoding following media upload

• transcoding on request

• transcoding progress reports

• asynchronous processing of transcodings

• one source available in multiple formats following transcoding

• linearly scalable transcoding farm available

Upload

• media storage by means of W3C protocols (HTTP POST/PUT)

• batch (ftp) operations with XML-controlled metadata

Miscellaneous

• system statistics

• system logging

• application, group and user quota

• generating stills from media

2.1 Description of the REST interfaces

The remainder of the document primarily consists of a summary of the MediaMosa REST interface. It comprises a description, the REST definition, a description of the parameters and their meanings and a sample request.

The REST definition comprises a URL request that contains a number of parameters (in {}) and ends with the GET or POST method (e.g. video/{asset_id}/play [GET]). The host name is not included in the description and, at the time of writing, reads http://app.vpx.kennisnet.nl/.

The Request parameters paragraph gives a detailed description of the parameters of the REST call, in which type 1 may be GET or POST. GET means that it must be listed in the query parameters; POST means that it must be provided via POST variables.

With some parameters it is possible to add “[]”, thus allowing multiple parameters with the same name, e.g. /asset?title=foo only searches for “foo” and the call /asset?title[]=foo&title[]=bar searches for assets with both the “foo” and “bar” title.

The examples use a number of default values: user_id=entree004, entree005, app_id=1 and app_id=28. These are completely random examples and only serve to clarify the example.

3. PLAYBACK

Playing back a video is the basis of MediaMosa. A video can be played back using an asset_id and a mediafile_id. At the moment, MediaMosa uses video streaming servers that can play different forms of WMV, Flash and Mpeg.

4. IDENTIFICATION OF THE END USER APPLICATION

Before an End User Application (EGA) can start using MediaMosa, it must identify itself by means of REST calls. Upon the first request of the identification process, a cookie is returned by the MediaMosa server (via the “Set-Cookie” HTTP header string). This cookie contains a session id, which must be returned as a cookie upon each subsequent request (via the “Cookie” HTTP header string). The EGA is given access to MediaMosa during the corresponding session.

The End User Application (EGA) is identified by means of the DBUS protocol. This protocol is actually a text protocol, while MediaMosa uses HTTP. In order to be able to use DBUS, the following change has been made: the client sends the DBUS messages as HTTP POST data (variable “dbus”) and the server returns the replies in XML (tag “dbus”). The URL for the POST requests is http://<vpx-url>/login.

A description of the DBUS protocol can be found on the following webpage:

http://dbus.freedesktop.org/doc/dbus-specification.html

MediaMosa uses the challenge-response method DBUS_COOKIE_SHA1 as an identification mechanism in DBUS.

1. The EGA sends “AUTH DBUS_COOKIE_SHA1 <username>” to MediaMosa, after which the latter returns the following information: “DATA vpx 0 <challenge>“

• C: AUTH DBUS_COOKIE_SHA1 username

• S: DATA vpx 0 b8225c6d20a6bef3d8dccfb3b5a30062

1. Along with the aforementioned <challenge>, MediaMosa has also sent a cookie in the form of: “SESS421aa90e079fa326b6494f812ad13e79=e490f6b992e33a41b9bbb7f101dbd300; expires=Thu, 08 May 2008 16:03:38 GMT; path=/”.
   In all requests to MediaMosa, the “SESS421aa90e079fa326b6494f812ad13e79=e490f6b992e33a41b9bbb7f101dbd300” session id must from now on be given as a cookie in the HTTP header.

2. The EGA generates a random text <random> and calculates the response string: sha1(<challenge>:<random>:<password>).
   The result is returned to MediaMosa in the following format: “DATA <random> <response>“. If the response is accepted, MediaMosa replies with “OK vpx”, otherwise it will say “REJECTED”.

• C: DATA 4b9d547c49c 58a345b427acde144b9d547c49cd1a2ec4a26190

• S: OK vpx

An example in PHP of how a client can authenticate himself is contained in Appendix A.

5. AUTHORISATION

MediaMosa makes it possible to screen off video files from other users. Access is determined with the following ACL (Access Control Lists) rules. The rights are set at media file level, making it possible to publish a number of low-quality videos under an asset, and to screen off high-quality copies from a group of users. Checks take place at the playback REST call (playproxy). If a media file is uploaded, it is not screened off, i.e. anyone can play it back. The moment one rule is set, this status changes to “fully screened off”, aside from the screening off rules given.

The playback check can be set to:

domain
An Internet domain name, e.g. only grant “surfnet.nl” access. All subdomains are also granted access to the domains given: flex.surfnet.nl for instance is also granted access in this example. There are two special domains: HO.group and ACADEMIA.group. If a check is placed on this domain group, all colleges of professional education and academic institutions respectively are allowed (check against the requestor's domain name).

realm
e.g. jan@xs4all.nl, or @surfnet.nl. In the first case, the realm must exactly match the requestor of the video. The second case is more flexible: all users that comply with *@surfnet.nl as well as any subdomains are granted access (e.g. piet@surfnet.nl, jan@flex.surfnet.nl, joris@flex1.z33.surfnet.nl). There are two special realms: @HO.group and @ACADEMIA.group. If these are used, the realm will be checked against the list of realms of colleges of professional education and academic institutions, respectively.

users
These are MediaMosa users, and are checked against the “user_id” field in the playback command (video/../play).

groups
These are MediaMosa users, and are checked against the “group_id” field in the playback command (video/../play).

applications
This is a special variation on the playback rights. It is possible to grant other applications affiliated to MediaMosa playback access to the videos. To that end, their application id must be known. The video can then be viewed in public within the other application, provided no realm/domain rights have been set. If they have been set on the media file, the other EGA must also comply with the domain/realm rights in order to be able to view the media file. User/group rights are generated for other EGAs, because user/groups are unique for each EGA; a media file can therefore never have a user/group from another EGA as owner/right.

6. Upload

MediaMosa offers three uploading methods for video files; via the end user application, directly via the end user browser by means of a POST upload form, or via FTP. The method via the end user application uses HTTP PUT, and puts no restrictions on the size of the files. The POST form has a restriction of 100 Mb. The method of letting an end user upload directly via POST has two steps: first a ticket is requested and then a file can be uploaded.

6.1 Upload via an end user browser

The diagram below shows the step-by-step procedure for uploading a video to MediaMosa.

4. The user clicks on a link to upload the video.

5. The EGA requests a ticket from MediaMosa. This is nothing more than a string that enables MediaMosa to identify the end user. The ticket is linked to an asset/media file, so that MediaMosa knows what to do with the uploaded file. The ticket is valid for one hour and is rendered invalid as soon as one upload has been made with it.

6. MediaMosa returns the ticket.

7. The EGA presents a HTML form with an action URL to the MediaMosa upload server. The URL of the upload server is returned as information when the ticket is requested. The EGA must also state a return on the form (see step 6).

8. The end user enters his file on the form and clicks on submit. This initiates the upload directly to the upload server.

9. When MediaMosa has received the file, it sends a redirect to the end user in order to return to the EGA website.

6.5 FTP

Another option is to upload files via FTP. The EGA can create FTP accounts by itself and manage them in its own application. After activation, a user can upload files to the server. The files must be uploaded with an identifying XML file so that MediaMosa knows what to do with them.

7. Transcoding

Transcoding is the conversion of video files from one format into another. MediaMosa supports Mpeg, WMV and Flash. Within these formats, MediaMosa can handle a large variety of parameters. Only original media files can be transcoded.

There are three options for transcoding. If no profile_id or tool is sent, a transcoding is started with a default profile. Other parameters are ignored. When a profile_id is sent, it will be transcoded via that profile. Other parameters are ignored. If a tool is given, a file_extension is also expected. In that case, a command is optional.

13. User / group management

MediaMosa does not offer a full set of user and group management functions. Since EGA is expected to deal with authentication of users in the EGA itself, this is also where user data must be stored. The user and group functions below are used to retrieve data from MediaMosa relating to use by users and groups.

There is no need to “create” users and groups within MediaMosa. As soon as an owner or group is allocated to an asset / collection / media file, this can be an as yet “unknown” user or group within MediaMosa. In these cases, this new user / group has no quota limit and falls directly within the limit of the EGA.

When retrieving multiple users (or groups), “known” and “unknown” users (or groups) are shown as a result in no particular order. The only difference with the “unknown” users is that no quota is given. An “unknown” user can be made “known” by allocating him a quota. This also applies to groups.

When retrieving a list of users / groups, data is linked to the users / groups on the list to a limited extent only. You will be able to see the details of the user / group only when you ask for a single user or group.

16. CQL - Contextual Query Language

CQL is a standard that is used to search by different platforms/databases via a simple string syntax. CQL stands for Contextual Query Language. To MediaMosa this is an advanced search method. An additional parameter will be used to pass a CQL string to MediaMosa. Within MediaMosa, this CQL string is converted into an SQL query, which in its turn is executed on the database. This additional parameter is exclusive compared to the other search parameters. That means that when the CQL string has been defined, no other search parameters will be used and will lead to an error message.

16.1 Basis of CQL

A CQL string comprises two components that are both optional:

[Searchinstructions] [sortby index]

The search commands are one or multiple search parameters, followed by the sort method. A search command comprises three components or one component;

• [index] [relation] [search parameter]
  title == “test”

• [search parameter]
  “test”

The index is the field name within which the search must be executed. The relation indicates the action and the search parameter represents that which must be searched for.

The search commands are linked by Booleans – AND, OR and NOT. The “PROX” Boolean is not supported in MediaMosa.

Example:

title == “test” OR description == “test”

The “sortby” component in the CQL determines the order of the results. MediaMosa only supports one-dimension sorting, by one index:

sortby title/sort.descending

16.2 Context set

The MediaMosa context set describes for CQL what is and is not possible within CQL. For instance, there is a MediaMosa context set for assets and collections. MediaMosa only allows its own MediaMosa context sets, and will therefore only allow MediaMosa context set definitions within the CQL.

16.3 RELATIONS

Relations are the definitions between index and the term.

=

The standard relation: equal to. The server will search for the corresponding relation for the type. For dates for instance, the relation == will be used, instead of =.

Examples:

1. title = “foo”

(Search for the word “foo” in title)

2. title = “foo test”

(Search for one of these words in title)

==

This relation indicates that the comparison must be exact.

Examples:

3. title == “foo”

(Search for the word “foo” in title)

4. title == “foo test”

(Search for the text “foo test” in title)

<>

This relation means unequal to.

Examples:

1. title <> “foo”

(title should not be equal to “foo”)

<, >, <=, >=

These relations compare their mutual relationship (smaller than, larger than, smaller than or equal to, larger than or equal to).

Examples:

1. dc.date > “2008-01-20 00:20:00”

adj

The “adj” relation determines that the search must be conducted within the index. This relation is the same as the “==” relation.

Examples:

1. dc.title adj “lord of the rings”
   (within the index, search for the text “lord of the rings”)

2. dc.title adj “blue shirt”
   (within the index, search for “blue”, followed by “shirts”)

all, any

The “all” and “any” relations are used when searching by multi terms. The “any” relation is the same as the “=” relation.

Examples:

1. dc.title all “lord rings”
   (the index must contain the words “lord” and “rings”)

2. dc.title any “lord rings”
   (the index must contain one of the words “lord” or “rings”)

within

The “within” relation is used to search within a range. You can do this for numbers, but also for dates.

1. dc.date within “2005 2006”
   (show everything with dc.date in 2005 and 2006)

2. beest.poten within “3 5”
   (show everything where beest.poten has anything between 3, 4 and 5 legs)

16.4 Relation modifiers

The relation additions are potential additional parameters that are allocated to a relation.

ignoreCase, respectCase

A standard aspect in the MediaMosa context is ignoreCase; ignoring the difference between lower and uppercase letters.

1. title =/ignoreCase “foo”

(Search for the word “foo” in title, regardless of lower or uppercase)

2. title =/respectCase “foo”

(Search for the word “foo” in title, but lower or uppercase must correspond)

3. title ==/respectCase “foo”

(Search for exact match of the word “foo” in title, but lower or uppercase must also correspond)

16.5 Masking, wildcards

Masking relates to special characters used in search terms.

Wildcard *

This character enables you to search by multiple combinations.

1. dc.title = “l*d”
   (retrieves everything that starts with “l” and ends in “d”)

Masking ?

This character enables you to mask a character.

1. dc.title = “fo?”
   (retrieves everything that starts with “fo” and ends in any other letter)

Anchor ^

This character indicates a match at the beginning or end. Look at the examples and notice the clear differences

1. dc.title = “cat^”
   (retrieves everything that ends in “cat”)

2. dc.title = “^cat”
   (retrieves everything that starts with “cat”)

3. dc.title == “^kat in de boom”
   (retrieves everything that starts with “kat in de boom”)

4. dc.title == “kat in de boom^”
   (retrieves everything that ends in “kat in de boom”)

5. dc.title = “^kat in de boom”
   (retrieves everything that starts with “cat” or contains one of the words in “in de boom”)

6. dc.title = “^kat ^hond boom^”
   (retrieves everything that starts with “kat” or “hond”, or ends in “boom”)

Backslash

Backslash (\) is used to escape characters such as “*”, “?”, quotation marks (“), “^” and itself (\). A backslash combined with any other character results in an error message.

1. dc.title = “\”foo dog\”, enzo”
   (Escape the quotation marks)

16.6 Booleans

The MediaMosa context does not use defined Booleans, as they are included in CQL by default. Please find a list of the default CQL Booleans below.

AND

The combination of two elements that must be true.

OR

The combination of two elements, one or more of which must be true.

NOT

The combination of two elements, the left one of which must be true, the right one not.

1. dc.title = foo NOT dc.title = dog
   (title must contain the word “foo”, but not the word “dog”)

2. NOT dc.title = dog
   (title should not contain the word “dog”)

3. NOT (dc.title = dog AND dc.title = foo)
   (title should not contain the words “dog” and “foo”, is the same as (dc.title != dog AND dc.title != foo))

PROX

The “PROX” Boolean is not supported in MediaMosa CQL and will result in an error message.

16.7 Boolean modifiers

Boolean modifiers only work on the “PROX” Boolean and are therefore not used by MediaMosa CQL.

16.8 Asset search and sort indexes

The MediaMosa index contains the index names used within the CQL string to indicate what to search by, e.g. “vpx:dc.creator == ‘jan’”. The “vpx:dc” is the context name and is optional, “creator == ‘jan’” will work in the same way. “dc.creator == ‘jan’” also acts in the same way.

MediaMosa indexes (CQL alias vpx)

• asset_id

• group_id

• owner_id

• provider_id

• reference_id

• mediafile_duration

• mediafile_container_type

• videotimestamp

• videotimestampmodified

• changed

• mime_type

• filename

• numofviews
  (the number of times an asset is viewed)

• numofplays
  (the number of times an asset is played)

Dublin Core (CQL alias vpx:dc / dc)

• title

• creator

• subject

• description

• publisher

• contributor

• date

• type

• format

• identifier

• source

• language

• relation

• coverage_temporal

• coverage_spatial

• rights

Qualified Dublin Core (CQL alias vpx:qdc / qdc)

• title_alternative

• description_abstract

• created

• issued

• hasformat

• isformatof

• format_medium

• format_extent

• license

• rightsholder

• isreferencedby

Content Search Profile (CQL alias vpx:czp / czp)

• diagramname

• identificationcode

• title

• language

• description

• keyword

• aggregationlevel

• version

• status

• type_learningmaterial

• intended_enduser

• context

• intended_agegroup

• costs

• copyrights

• rights_description

• classification

16.9 Collection search and sort indexes (CQL alias vpx:collection)

• title

• description

• owner_id

• group_id

• created

• changed

• private

• public

• category

• numofvideos

16.10 ACL search rules (CQL alias vpx:acl)

• aut_app

• aut_group

• aut_user

• aut_domain

• aut_realm

• aut_realm_prefix

• is_protected
  
  
  

The ACL context set is specifically used for the retrieval of certain ACL rules on assets. Retrieval always takes place within the app(s) of the EGA. It is not possible to retrieve an asset or assets in this way if you as a EGA have not been granted access. Make sure that you use this special context set for internal purposes only; as soon as you use this context, you always search within all assets that you have access to as EGA/APP. This means no access checks are carried out, except the master/slave access check. So you are always looking within your own assets, and possibly slave assets.

In order to search within assets that fall under a certain app (enabling you to exclude master or slaves, for instance):
aut_app == 5

In order to show only assets that do not fall under a certain app (enabling you to see slaves, in case master app has id 5):
aut_app <> 5

Show me all unprotected assets:
is_protected == false

Show me all protected assets:
is_protected == true

Show me all assets that have been set via a certain ACL group:
aut_group == “^usergroup 1^”

Show me all assets that have not been set via a certain ACL group:
aut_group <> “^usergroup 1^”

Show me all assets that have been set via a certain user (this is not the owner):
aut_user == “^user^”

Show me all assets that have not been set via a certain user (this is not the owner):
aut_user <> “^user^”

Show me all assets that have been set on a certain domain:
aut_domain == “^foo.nl^”

Show me all assets that have not been set on a certain domain:
aut_domain <> “^foo.nl^”

Show me all assets that have been set on a certain realm:
aut_realm == “^@foo.nl^”

Show me all assets that have not been set on a certain realm:
aut_realm <> “^@foo.nl^”

Show me all assets that have been set on a certain realm in combination with prefix:
aut_realm == “^@foo.nl^” AND aut_realm_prefix == “^johndoe^”

Show me all assets that have not been set on a certain realm in combination with prefix:
aut_realm <> “^@foo.nl^” AND aut_realm_prefix <> “^johndoe^”

16.11 Search for parameters that fall outside CQL

A lot of parameters, such as “granted” and “hide_empty_assets”, cannot be set via CQL. They must therefore be given in the normal way, in addition to the “cql” parameter.

17. FAQ

Q: How do I create a list of stills (storyboard) from a video?

A: MediaMosa saves one still per asset, so the EGA will have to download and save the stills itself. The still request accepts a time parameter that is used in order to generate the still. This request can be made multiple times, after which the still can be retrieved and stored.

Q: How do I save a fragment of a video file?

A: MediaMosa accepts start and end times of assets. This makes it possible to upload a personally created ASX file that contains a reference to the original file, including start and end time. This fragment can subsequently be requested separately, without having to save the fragment twice.

Q: How do I remove the objects from a user?

A: There are two options. MediaMosa has built-in a composed REST call / change_ownership (see description), making it possible for objects to change user. You can also remove an object from a user by first requesting the object of that user (parameter: owner_id=…) and requesting the relevant /delete call.

Q: ROC Rotterdam has videos on MediaMosa that can only be played for that institution. ROC The Hague can also view them.

A: Use /mediafile/{mediafile_id}/acl to add the rules for the other institution.