RAWS Metadata Concepts
Contents |
Overview
After you have uploaded a file to the CDN, you can use the META content resource to attach metadata to your file. The metadata is not injected into the file itself, but stored separately by RAWS so it can be used later to provide detailed information about your media. For example, client applications can search for files based on tags or metadata values, make dynamic selections (e.g. generate playlists), display extra information, insert ads, use metadata to grant authorization...
The META ext resource allows you to retrieve lists of video's on the CDN based on a metadata query. These lists may be used directly by third party applications or end-users.
For manual metadata management, you can use the META administration interface. This is a dedicated web application which provides you with an overview of your existing metadata. You can access it at the following URL: http://meta.meta01.rambla.be/admin/.
The 'tag' and 'meta' objects
Currently, the RAWS APIs make a distinction between two types of metadata objects: the plain 'tag' object, and the more generic 'meta' object. You can use either one, depending on your needs.
tag object
The tag object is intended for simple tagging. It doesn't have any attributes, only a value (= the tag that you are attaching to your file(s)).
meta object
The meta object is more flexible. Each meta object is uniquely identified by two aspects: its meta_name (= name of the metadata object) and its vocab (vocabulary). For example:
{
"vocab": "raws",
"meta_name": "movies"
}
A meta object may have a text value. For example, the Dublin Core 'contributor' object, belonging to the 'dc' vocabulary, has a text value "Rambla":
{
"vocab": "dc",
"meta_name": "Contributor",
"text": "Rambla"
}
A meta object may have a lang value, which may contain the ISO 639-1 language abbreviation for the object. This will allow you to retrieve metadata in different languages by using a query-string parameter.
{
"vocab": "dc",
"meta_name": "Title"
"text": "About Rambla",
"lang": "en"
}
A meta object may also have attributes which further specify the value, define relations, etc. You can simply include them in the meta object, when setting it. For example, the 'Media RSS' description object has a 'type' attribute:
{
"vocab": "media",
"meta_name": "description"
"text": "This was some really bizarre band I listened to as a young lad.",
"lang": "en",
"type": "plain"
}
Vocabularies
Each meta object belongs to one (and only one) vocabulary. A vocabulary consists of a name and an XML namespace (= URL) which are used to qualify the metadata names, depending on the protocol that is being used for formatting (e.g. ATOM, RSS, JSON). For example: when retrieving XML formatted data, the vocabulary name is being used as an XML namespace shortener. The vocab resource allows you to create your own vocabularies.
For instance: to create a Dublin Core vocabulary, you send a HTTP POST request to "http://meta.cdn0x.rambla.be/vocab/{username}/" with an entry in the request body that contains following params:
{
"entry": {
"content": {
"params": {
"name": "dc",
"xml_namespace": "http://purl.org/dc/elements/1.1/",
}
},
},
}
Meta objects require a vocabulary
When you pass a meta object as a parameter, its vocabulary always needs to be specified. For convenience sake, when you POST a meta resource that contains vocabulary name which don't yet exist, META will create the vocabulary on the fly and set its namespace to a conventional URL. Nevertheless, it is better practice to define your vocabularies before using them.
Note that you can also use the 'meta' object for simple tagging, by setting only its meta_name and vocabulary and not giving it a value.
Using metadata
The content resource allows you to set and retrieve 'tag' and 'meta' objects for your media on the CDN. It also allows you do searches based on metadata. Each content instance represents a media item, which may consist out of multiple files on the CDN. For example, a single video may be transcoded into multiple formats, have playlists files for adaptive streaming, thumbnails... which are all stored in a separate file on the CDN. The content instance is intended as a single representation for all of these files, to which metadata can be attached. This allows clients to set/get metadata for a media item, without having to worry about the underlying files on the CDN.
A content resource will be automatically created for those media items that have been generated by the Rambla Transcoding Service (RATS), either through the API or through a hotfolder. You can retrieve the URL for this content resource by parsing the CDN report or by querying the URL of your job request. In this case, the META resource will contain all technical metadata.
When you upload the media files to the CDN yourself, you can create a META instance for your media item by sending a POST content request.
Query-string arguments allow you to retrieve content lists based on either tag names or meta objects. For example, the following URL will return all files that have "Rambla" or "Monty" as their Contributor:
http://meta.cdn01.rambla.be/meta/monty/?meta=dc:Contributor:Rambla,dc:Contributor:Monty
Note that all access to the 'content' resource requires authentication to the META service using your Rambla user credentials. To make your metadata publicly available without the interference of a client application, you should use the 'ext' resource.
Publishing metadata
The ext resource returns a list of media items, in which each entry contains both the (download and/or streaming) location of your multimedia(s) file and the attached metadata. Client application or third-party users can retrieve these lists (e.g. as RSS or ATOM feeds) based on the same selection criteria (query or search) as for the content resource. You can choose to make the ext resource publicly available or require authentication.
Differences between the 'meta' and 'ext' resource:
- The 'ext' resource can not be used to manage metadata. It only serves to return existing metadata (read-only).
- The 'meta' resource always requires authentication by the user owning the files. Access to the 'ext' resource may be public (optional).
- The 'ext' resource can be returned in different representations.
