API
  • RSS Feed

Last modified on 8/22/2013 12:36 PM by User.

Tags:

API

Getting Started

T3Media has the world’s largest video content library, with the searchability to browse volumes and the depth to pinpoint something entirely specific. The content in our store is protected, so you can only access those portions for which you have permissions. Where you do have access, the API provides a means to:

Search: Find categories, types, or titles, all searchable properties of content. Discover important technical information about content; properties such as title, release date, length, format, codec, aspect ratio. Or get event-based metadata with timecodes and attributes.
View: Preview content, watch clips, or view long form content in full where you own or have rights associated with it.

The public API is implemented in REST (REpresentational State Transfer) over HTTP. We have endeavored to use the strictest definition of REST, meaning that our data is noun-oriented, using the four GET, POST, PUT, and DELETE HTTP "verbs" as the primary verbs in the interface. All data communication uses either name-value pairs for simple data, or XML for structured data.

In addition to the REST API used for data communication, a Flash video player is also available which is necessary to access most video content.

By utilizing our API or video player, you are subject to T3Media’s Terms and Conditions

 

This Document

You are currently reading the documentation for the T3M API. This page is designed to give you an overview of the API, how it works, and what you can do with it. Following a link off of this page will take you to more in-depth documentation that will only be useful if you want to spend more time learning how to create a program or system to interact with the API.

Much of the information is interrelated, so we recommend giving this document a quick once-over to get the general ideas used in the API, then go back through it in depth.

 

Supported Formats

We use XML formats for both requesting and delivery of data, although many requests can be made just using parameters in the HTTP URL. This format can be specified in the HTTP header by setting the "Accept" field to application/xml.

Alternatively, the desired format can be specified as a query parameter as mimeType=application/xml.

If not specified, then XML is assumed. XML is currently the only supported format, and is the default, but if other formats (JSON, SOAP, etc) are supported in the future, setting the "Accept" parameter will matter.

 

Nouns vs. Verbs

While some standards like SOAP approach an interface using a verb-based approach (like "change the country in the address to Germany", "sell a t-shirt to customer Bob Smith", or "insert clip X into clip bin Y"), REST uses a noun-based approach. In REST, there are only 4 verbs: retrieve, update, create, and delete, and everything else is a noun, like "update the address country to Germany", "create an order whose product is a t-shirt and whose customer is Bob Smith", or "create a bin-clip whose clip is X and whose bin is Y."

So the versatility of a REST interface is dependent almost exclusively on the types and relationships between nouns.

 

T3Media Verbs


The only 4 verbs in the interface are:

  • Retrieve, which is implemented using an HTTP GET.
  • Update, which is implemented using an HTTP POST or PUT.
  • Create, which is implemented using an HTTP PUT or POST.
  • Delete, which is implemented using an HTTP DELETE.

T3Media verb reference

 

T3Media Nouns


T3Media's interface contains nouns with the following properties:

  • Each noun has a type which identifies what function it serves. Types are hierarchical and reflect the relationship between the nouns. For example, one noun is a user, another is a user/address where this indicates that this noun is an address for a user, as opposed to the account/address, which would be an address for an account, and may have different properties.
  • Each noun in the system has an ID which uniquely identifies the noun. An ID is inherently meaningless, usually (but not always) a random number assigned when the noun is created. IDs are used to refer to nouns, as in "retrieve user ID 37190" or "delete transcode 6734529-20110505132944." Many nouns also have names, and if the name is unique then it may also be used like an ID to identify a noun like "get user with email address Bob.Smith@t3media.com" or "get clip with name 226059_009"
  • Every noun comes with an internal reference to the URL that refers to itself, so you always know where the noun originally came from.
  • Nouns can also have attributes, like a user may have the attributes firstName, lastName, or title. An attribute can be a string, like "Bob", "Smith", and "Mr."
  • Nouns can also have contained nouns, like a user may contain user/addresses or user/permissions, and the user/address may contain a user/address/country, etc. Each contained noun is inside a container noun.
    • Contained nouns only have meaning inside their container, but can still be accessed independently. That is, each user/address still has it's own unique ID that can be used to get the user/address without also getting the user that contains it.
    • Every contained noun has, as an attribute, the URL necessary to find it's container, likewise container nouns may refer to their contained nouns by either URL or the actual noun (depending on whether you use the shallow or deep API requests - more on this later.)
  • Nouns may also have referenced nouns, which are other nouns that the noun points to, but does not contain. For example, an order almost certainly contain a reference to the user that placed the order, and the clips that are in the order. The main difference between a referenced and a contained noun is that a referenced noun is independent of the referencing noun, and is usually referenced by multiple referencing nouns (e.g. a user can create multiple orders, a clip can be purchased multiple times).

T3Media noun reference (this is really the heart of the documentation)

 

URLs

Because the interface is REST over HTTP, that means that the primary means of communication is HTTP requests (just like a browser uses), and therefore relies heavily on URLs.

T3Media maintains a separate address space for API requests, which is http://api.t3platform.com, and all API requests should be directed to this server. Within this address space, the API is located at video/services.

URLs are generally in one of the following formats:

http://api.t3platform.com/video/services/noun/ID
http://api.t3platform.com/video/services/noun

where the first form is used to retrieve data about or update the data of the noun that has the ID or name. The second form is used for performing queries or creating a new noun that doesn't have an ID yet.

 

 

Authorization

Each URL sent to the system must be accompanied by an authorization value which demonstrates that the URL was sent by the person that says they sent it. In a web server, you generally supply a name and password one time during logon, then your browser maintains a validation token that proves that you are still the same person you were when you logged on. Since the API is not used in an environment where the validation token is maintained for you ("behind the scenes" if you will), every request made to the API requires a token -- this is basically "logging into" the API on each request.

How to authorize an API call

 

Views

All URL interfaces accept the optional view parameter. This parameter can be used to get custom views of nouns. For example, specifying view=count when requesting a search noun will cause just the number of results to be returned faster than actually getting the results and counting them.

Other view parameters can change page sizes or modify the amount of detail returned in the response.

View parameters

 

Implementation

The reference implementation of the API interface is a simple UNIX bash shell script. This demonstrates the minimum set of code that is required to make a valid API call.

Sample UNIX command line implementation

Sample URL implementation

Application Development

 

Usage

Transcoding a clip