Skip to content

Movida Resource: Title

Jump to bottom Edit New page
Paco Guzmán edited this page Aug 7, 2014 · 24 revisions

Introduction

A title is an individual title, like a specific program or movie, or an episode of a series.

It looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<title>
  <id type="integer">1</id>
  <title>Forrest Gump</title>
  <name>Forrest Gump</name>
  <external-id>C5080530001</external-id>
  <title-type>feature</title-type>
  <tags>Drama,Action</tags>
  <link href="http://movida.example.com/api/titles/1" rel="self"/>
  <link href="http://movida.example.com/api/titles/1/schedule" rel="schedule"/>
  <link href="http://movida.example.com/api/titles/1/availability_windows" rel="availability_windows"/>
  <link href="http://movida.example.com/api/titles/1/title_groups" rel="title_groups"/>
  <link href="http://movida.example.com/api/licensors/114" rel="licensor"/>
  <link href="http://movida.example.com/api/titles/1/images" rel="images"/>
  <link href="http://movida.example.com/api/titles/1/metadata" rel="metadata"/>
  <link href="http://movida.example.com/api/titles/1/blackouts" rel="blackouts"/>
</title>

As you can see, a title has a schedule (which will contain all of the instances of that title in any of the available VoD platforms), and it also references its "series", its "licensor" and its "metadata". The "self" link is pointing to the title itself, and it is a unique URL that will not change overtime.

Title attributes

  • id (mandatory): Movida internal identifier of the title. It shouldn't be provided in the creation of the resource, because Movida will assign that value.
  • external-id (optional): the identifier of the title in the external system. If provided, it has to be unique in the scope of the company.
  • title-type (mandatory): the type of title. Possible values are "episode", "feature", "open", "promo", "ad" and "bumper".
  • episode-number (optional): the number of episode. This attribute only makes sense when the title is an episode and belongs to a series.
  • name (mandatory): the name of the title.
  • tags (optional): the list of tags separated by commas of the title.

GET A list of all titles

To returns a list of all titles in your account (this can be a bit massive - note that at the moment there is no paging available), it would go like this:

$ curl --digest -u robot_user http://movida.example.com/api/titles

And would yield something like:

<?xml version='1.0' encoding='utf-8' ?>
<titles type='array'>
  <title>
    <id type="integer">73</id>
    <title>E01, Episode 1</title>
    <name>Episode 1</name>
    <episode-number type="integer">1</episode-number>
    <external-id>C5147630001</external-id>
    <title-type>episode</title-type>
    <tags>Drama,Action</tags>
    <link href="http://movida.example.com/api/titles/73" rel="self"/>
    <link href="http://movida.example.com/api/titles/73/schedule" rel="schedule"/>
    <link href="http://movida.example.com/api/titles/73/availability_windows" rel="availability_windows"/>
    <link href="http://movida.example.com/api/title_groups/41" rel="series"/>
    <link href="http://movida.example.com/api/licensors/29" rel="licensor"/>
    <link href="http://movida.example.com/api/titles/73/images" rel="images"/>
    <link href="http://movida.example.com/api/titles/73/metadata" rel="metadata"/>
  </title>
  <title>
    <id type="integer">30391</id>
    <title>The Green Lantern</title>
    <name>The Green Lantern</name>
    <external-id>C5150630007</external-id>
    <title-type>feature</title-type>
    <tags>Drama,Action</tags>
    <link href="http://movida.example.com/api/titles/30391" rel="self"/>
    <link href="http://movida.example.com/api/titles/30391/schedule" rel="schedule"/>
    <link href="http://movida.example.com/api/titles/30391/availability_windows" rel="availability_windows"/>
    <link href="http://movida.example.com/api/licensors/207" rel="licensor"/>
    <link href="http://movida.example.com/api/titles/30391/images" rel="images"/>
    <link href="http://movida.example.com/api/titles/30391/metadata" rel="metadata"/>
  </title>
</titles>

Accepted Parameters

external_id - You can filter the list of titles by passing in an external_id. Because Movida was designed to integrate with external content management system, it has an attribute called 'external_id' for every series and every title. This attribute can be used to store the ID of that specific item in an external system.

If you needed to access a title by external_id, you can do so by passing the parameter external_id to the list of titles, like this:

$ curl --digest -u robot_user http://movida.example.com/api/titles?external_id=C5147630001

Which would filter by the passed external_id like:

<?xml version="1.0" encoding="UTF-8"?>
<titles type="array">
  <title>
    <id type="integer">73</id>
    <title>E01, Episode 1</title>
    <name>Episode 1</name>
    <episode-number type="integer">1</episode-number>
    <external-id>C5147630001</external-id>
    <title-type>episode</title-type>
    <tags>Drama,Action</tags>
    <link href="http://movida.example.com/api/titles/73" rel="self"/>
    <link href="http://movida.example.com/api/titles/73/schedule" rel="schedule"/>
    <link href="http://movida.example.com/api/titles/73/availability_windows" rel="availability_windows"/>
    <link href="http://movida.example.com/api/title_groups/41" rel="series"/>
    <link href="http://movida.example.com/api/licensors/29" rel="licensor"/>
    <link href="http://movida.example.com/api/titles/73/images" rel="images"/>
    <link href="http://movida.example.com/api/titles/73/metadata" rel="metadata"/>
  </title>
</titles>

GET a specific title

This is a good way to recover information about a specific title. We recommend that you use its full URL as the ID that you store in your systems, if you ever need to re-access it. Following the previous example:

$ curl --digest -u robot_user http://movida.example.com/api/titles/73

<?xml version='1.0' encoding='utf-8' ?>
<title>
  <id type="integer">73</id>
  <title>E01, Episode 1</title>
  <name>Episode 1</name>
  <episode-number type="integer">1</episode-number>
  <external-id>C5147630001</external-id>
  <title-type>episode</title-type>
  <tags>Drama,Action</tags>
  <link href="http://movida.example.com/api/titles/73" rel="self"/>
  <link href="http://movida.example.com/api/titles/73/schedule" rel="schedule"/>
  <link href="http://movida.example.com/api/titles/73/availability_windows" rel="availability_windows"/>
  <link href="http://movida.example.com/api/title_groups/41" rel="series"/>
  <link href="http://movida.example.com/api/titles/73/title_groups" rel="title_groups"/>
  <link href="http://movida.example.com/api/licensors/29" rel="licensor"/>
  <link href="http://movida.example.com/api/titles/73/images" rel="images"/>
  <link href="http://movida.example.com/api/titles/73/metadata" rel="metadata"/>
</title>

Remember you can use the 'expand me some nodes trick' if you want to, for instance, find out what is the schedule of a particular title

$ curl --digest -u robot_user http://movida.example.com/api/titles/73?expand=schedule,schedulings

This would expand the 'rel=schedule' link, and then would also expand the 'rel=schedulings' link inside the schedule, yielding something like:

<?xml version="1.0" encoding="UTF-8"?>
<title>
  <id type="integer">73</id>
  <title>E01, Episode 1</title>
  <name>Episode 1</name>
  <episode-number type="integer">1</episode-number>
  <external-id>C5147630001</external-id>
  <title-type>episode</title-type>
  <tags>Drama,Action</tags>
  <link href="http://movida.example.com/api/titles/73" rel="self"/>
  <link href="http://movida.example.com/api/titles/73/schedule" rel="schedule">
    <schedule>
      <link href="http://movida.example.com/api/titles/73/schedule/schedulings" rel="schedulings">
        <schedulings type="array">
          <scheduling>
            <id type="integer">23817</id>
            <put-up type="datetime">2009-10-01T00:00:00+01:00</put-up>
            <take-down type="datetime">2010-12-22T23:59:59+00:00</take-down>
            <scheduling-type>archive</scheduling-type>
            <rights-status>cleared</rights-status>
            <tags>Drama,Action</tags>
            <link href="http://movida.example.com/api/schedulings/23817" rel="self"/>
            <link href="http://movida.example.com/api/title_groups/41" rel="title_group"/>
            <link href="http://movida.example.com/api/titles/73" rel="title"/>
            <link href="http://movida.example.com/api/schedulings/23817/assets" rel="assets"/>
            <link href="http://movida.example.com/api/platforms/1" rel="platform"/>
          </scheduling>
        </schedulings>
      </link>
      <link href="http://movida.example.com/api/titles/73" rel="title"/>
    </schedule>
  </link>
  <link href="http://movida.example.com/api/titles/73/availability_windows" rel="availability_windows"/>
  <link href="http://movida.example.com/api/title_groups/41" rel="series"/>
  <link href="http://movida.example.com/api/titles/73/title_groups" rel="title_groups"/>
  <link href="http://movida.example.com/api/licensors/29" rel="licensor"/>
  <link href="http://movida.example.com/api/titles/73/images" rel="images"/>
  <link href="http://movida.example.com/api/titles/73/metadata" rel="metadata"/>
</title>

Creating titles

For creating titles, you just need to POST a proper XML title representation (similar to the ones you get when fetching a title) to the proper URL. That URL can be found in a link whose rel is titles, like the one found in the API root (for creating titles which don't belong to any series) or in any series (for creating titles belonging to that series). The only mandatory field is the name, the rest are optional.

Creating a standalone title (aka. feature)

For example, this POST would create a film (we'll use curl's @ option, which reads data to be posted from a file):

$ cat title.xml 

<title>
  <name>13 Assassins</name>
  <external-id>123456</external-id>
  <link rel="licensor" href="http://movida.example.com/api/licensors/4"/>
  <title-type>feature</title-type>
  <tags>Drama,Action</tags>
</title>

Note that the licensor URL must be of one licensor that already exists in the system, otherwise it will default to "No Licensor", since it is optional. See how to create licensors in the Movida Resource: Licensor page

$ curl -u robot:yourpassword --digest -H "Content-Type: application/xml" -X POST -d @title.xml "http://movida.example.com/api/titles"

Movida will return the full XML of the title just created:

<?xml version="1.0" encoding="UTF-8"?>
<title>
  <id type="integer">4</id>
  <title>13 Assassins</title>
  <name>13 Assassins</name>
  <external-id>123456</external-id>
  <title-type>feature</title-type>
  <tags>Drama,Action</tags>
  <link rel="self" href="http://movida.example.com/api/titles/4"/>
  <link rel="schedule" href="http://movida.example.com/api/titles/4/schedule"/>
  <link rel="licensor" href="http://movida.example.com/api/licensors/4"/>
  <link rel="images"   href="http://movida.example.com/api/titles/4/images"/>
  <link rel="metadata" href="http://movida.example.com/api/titles/4/metadata"/>
</title>

Creating an episode to an existing series

To create an episode of a series, you only need to POST the title XML to the URL in the link rel=titles of the series you want to add the episode to.

Assuming the URL for the episodes of a series is http://movida.example.com/api/title_groups/1/titles and the following XML:

$ cat episode.xml 

<title>
  <name>Episode 1</name>
  <external-id>123456</external-id>
  <episode-number>1</episode-number>
  <title-type>episode</title-type>
  <tags>Drama,Action</tags>
</title>

The following command would create it as part of the series' episodes:

$ curl -u robot:yourpassword --digest -H "Content-Type: application/xml" -X POST -d @episode.xml "http://movida.example.com/api/title_groups/1/titles"

This would return the XML of the new episode - note how it references the series we've just associated it to:

<?xml version="1.0" encoding="UTF-8"?>
<title>
  <id type="integer">30392</id>
  <title>E01, Episode 1</title>
  <name>Episode 1</name>
  <episode-number type="integer">1</episode-number>
  <external-id>123456</external-id>
  <title-type>episode</title-type>
  <tags>Drama,Action</tags>
  <link href="https://staging-movida.bebanjo.net/api/titles/4" rel="self"/>
  <link href="http://movida.example.com/api/titles/30392/schedule" rel="schedule"/>
  <link href="http://movida.example.com/api/titles/30392/availability_windows" rel="availability_windows"/>
  <link href="http://movida.example.com/api/title_groups/1" rel="series"/>
  <link href="http://movida.example.com/api/titles/30392/title_groups" rel="title_groups"/>
  <link href="http://movida.example.com/api/licensors/114" rel="licensor"/>
  <link href="http://movida.example.com/api/titles/30392/images" rel="images"/>
  <link href="http://movida.example.com/api/titles/30392/metadata" rel="metadata"/>
</title>

Updating titles

You can update titles issuing a PUT request to the URL of a given title, as the following example illustrates. This example only updates the title's name, but also the external-id, the licensor and the episode number can be updated.

$ cat title.xml 

<title>
  <name>13 Assassins (English version)</name>
</title>

Now we send the XML as the body of a PUT request to the title's URL

$ curl -u robot:yourpassword --digest -H "Content-Type: application/xml" -X PUT -d @title.xml "http://movida.example.com/api/titles/4"

The PUT request would return the updated XML of the title:

<?xml version="1.0" encoding="UTF-8"?>
<title>
  <id type="integer">4</id>
  <title>13 Assassins (English version)</title>
  <name>13 Assassins (English version)</name>
  <external-id>C5144140351</external-id>
  <title-type>feature</title-type>
  <tags>Drama,Action</tags>
  <link href="http://movida.example.com/api/titles/4" rel="self"/>
  <link href="http://movida.example.com/api/titles/4/schedule" rel="schedule"/>
  <link href="http://movida.example.com/api/titles/4/availability_windows" rel="availability_windows"/>
  <link href="http://movida.example.com/api/titles/4/title_groups" rel="title_groups"/>  
  <link href="http://movida.example.com/api/licensors/4" rel="licensor"/>
  <link href="http://movida.example.com/api/titles/4/images" rel="images"/>
  <link href="http://movida.example.com/api/titles/4/metadata" rel="metadata"/>
</title>

Deleting titles

The following example shows how to destroy a particular title. Only a DELETE HTTP request to its URL is required:

$ curl -u robot:yourpassword --digest -H "Content-Type: application/xml" -X DELETE "http://movida.example.com/api/titles/4"

The DELETE request doesn't return anything, as that title is now gone.

Deleting a title causes some of its related resources to be removed:

  • linear schedulings
  • schedulings
  • assets
  • availability windows
Add a custom footer
Add a custom sidebar
Clone this wiki locally