Skip to content

Movida Resource: Title Group

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

Introduction

A Title Group is exactly that, a group of titles. Currently in Movida there are two types:

Series (series)

This is generally a "season", and a title can only belong to one series. A title that belongs to a series is an episode. An example would be "Season 1 of CSI: Crime Scene Investigation". A specific episode (say, where Grissom, through a long shot extrapolation discovers who the killer was), can only belong to one season at a time. Hmmm... Ok, bad example.

It looks like this (notice the title-group-type):

<title-group>
  <id type='integer'>180</id>
  <name>CSI: Crime Scene Investigation</name>
  <external-id>14320</external-id>
  <title-group-type>series</title-group-type>
  <season-number>1</season-number>
  <tags>Drama,Action</tags>
  <link href="https://movida.example.com/api/title_groups/180/titles" rel="titles"></link>
  <link href="https://movida.example.com/api/title_groups/180/schedule" rel="schedule"></link>
  <link href="https://movida.example.com/api/title_groups/180/metadata" rel="metadata"></link>
  <link href="https://movida.example.com/api/title_groups/180/images" rel="images"></link>
  <link href="https://movida.example.com/api/title_groups/180/blackouts" rel="blackouts"></link>
</title-group>

NOTE: This resource links can be expanded using the expand option except the blackouts link.

Collection (title_group)

A collection is a group of titles of any type (episodes, features, ads, promos…). A title can belong or not to one or many collections. Like this, Movida enables its users to package titles of different series together so that they can be scheduled on VoD. An example would be "CSI: Trilogy", an special that contains three episodes, one from each strand (Vegas, Miami and New York). Those episodes belong to their specific series, but they can be packaged in various ways.

It looks like this:

<title-group>
  <id type='integer'>215</id>
  <name>CSI: Trilogies</name>
  <external-id></external-id>
  <title-group-type>title_group</title-group-type>
  <tags>Drama,Action</tags>
  <link href="https://movida.example.com/api/title_groups/215/titles" rel="titles"></link>
  <link href="https://movida.example.com/api/title_groups/215/schedule" rel="schedule"></link>
  <link href="https://movida.example.com/api/title_groups/215/metadata" rel="metadata"></link>
  <link href="https://movida.example.com/api/title_groups/215/images" rel="images"></link>
</title-group>

NOTE: This resource links can be expanded using the expand option

Title Group attributes

  • id (mandatory): Movida internal identifier of the title group. 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 group in the external system. If provided, it has to be unique in the scope of the company.
  • title-group-type (mandatory): the type of title group. Possible values are "series" (for series) and "title_group" (for collections).
  • name (mandatory): the name of the title group.
  • tags (optional): the tags as a list separated by commas of the title group.

Accessing Title Groups

Title groups can be accessed always by navigating the corresponding nodes, and the current options are:

GET A list of all title groups

To return a list of all title groups 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 https://movida.example.com/api/title_groups

And would yield something like:

<?xml version='1.0' encoding='utf-8' ?>
<title-groups type='array'>
  <title-group>
    <id type='integer'>1</id>
    <name>Sunrise</name>
    <external-id>23450</external-id>
    <title-group-type>series</title-group-type>
    <season-number>1</season-number>
    <tags>Drama,Action</tags>
    <link href="https://movida.example.com/api/title_groups/1/titles" rel="titles"></link>
    <link href="https://movida.example.com/api/title_groups/1/schedule" rel="schedule"></link>
    <link href="https://movida.example.com/api/title_groups/1/metadata" rel="metadata"></link>
    <link href="https://movida.example.com/api/title_groups/1/images" rel="images"></link>
  </title-group>
  <title-group>
    <id type='integer'>2</id>
    <name>Peppa Pig: S02</name>
    <external-id>11512</external-id>
    <title-group-type>series</title-group-type>
    <season-number>2</season-number>
    <tags>Drama,Action</tags>
    <link href="https://movida.example.com/api/title_groups/2/titles" rel="titles"></link>
    <link href="https://movida.example.com/api/title_groups/2/schedule" rel="schedule"></link>
    <link href="https://movida.example.com/api/title_groups/2/metadata" rel="metadata"></link>
    <link href="https://movida.example.com/api/title_groups/2/images" rel="images"></link>
  </title-group>
</title-groups>

Accepted Parameters

external_id - You can filter the list of title groups by passing in an external_id. Because Movida was designed to integrate with external content management systems, 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_group by external_id, you can do so by passing the parameter external_id to the list of title_groups, like this:

$ curl --digest -u robot_user https://movida.example.com/api/title_groups?external_id=11523

Which would filter by the passed external_id like:

<?xml version='1.0' encoding='utf-8' ?>
<title-groups type='array'>
  <title-group>
    <id type='integer'>2</id>
    <name>Peppa Pig: S02</name>
    <external-id>11512</external-id>
    <title-group-type>series</title-group-type>
    <season-number>2</season-number>
    <tags>Drama,Action</tags>
    <link href="https://movida.example.com/api/title_groups/2/titles" rel="titles"></link>
    <link href="https://movida.example.com/api/title_groups/2/schedule" rel="schedule"></link>
    <link href="https://movida.example.com/api/title_groups/2/metadata" rel="metadata"></link>
    <link href="https://movida.example.com/api/title_groups/2/images" rel="images"></link> 
  </title-group>
</title_groups>

GET a specific title group

This is a good way to recover information about a specific title_group. 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 https://movida.example.com/api/title_groups/2
<?xml version='1.0' encoding='utf-8' ?>
<title-group>
  <id type='integer'>2</id>
  <name>Peppa Pig: S02</name>
  <external-id>11512</external-id>
  <title-group-type>series</title-group-type>
  <season-number>2</season-number>
  <tags>Drama,Action</tags>
  <link href="https://movida.example.com/api/title_groups/2/titles" rel="titles"></link>
  <link href="https://movida.example.com/api/title_groups/2/schedule" rel="schedule"></link>
  <link href="https://movida.example.com/api/title_groups/2/metadata" rel="metadata"></link>
  <link href="https://movida.example.com/api/title_groups/2/images" rel="images"></link>
</title-group>

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_group

$ curl --digest -u robot_user https://movida.example.com/api/title_groups/2?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-group>
  <id type='integer'>2</id>
  <name>Peppa Pig: S02</name>
  <external-id>11523</external-id>
  <title-group-type>series</title-group-type>
  <season-number>2</season-number>
  <tags>Drama,Action</tags>
  <link href="https://movida.example.com/api/title_groups/2/titles" rel="titles"></link>
  <link href="https://movida.example.com/api/title_groups/2/metadata" rel="metadata"></link>
  <link href="https://movida.example.com/api/title_groups/2/images" rel="images"></link>
  <link href="https://movida.example.com/api/title_groups/2/schedule" rel="schedule">
    <link href="https://movida.example.com/api/title_groups/2/schedule/schedulings" rel="schedulings">
      <schedulings type='array'>
        <scheduling>
          <id type='integer'>40</id>
          <put-up type='datetime'>2010-03-31T22:00:00Z</put-up>
          <take-down type='datetime'>2010-06-01T21:59:59Z</take-down>
          <scheduling-type>archive</scheduling-type>
          <tags>Drama,Action</tags>
          <link href="https://movida.example.com/api/title_groups/2" rel="title_group"></link>
          <link href="https://movida.example.com/api/titles/581" rel="title"></link>
        </scheduling>
      </schedulings>
    </link>
  </link>
</title-group>

Creating title groups

Creating new title groups is easy, you just have to post a title group resource (like the ones you get when retrieving title groups) to the URL of a link whose rel is title_groups, like the one you'll find in the API root:

$ curl -u robot:yourpassword --digest "http://localhost:3000/api"
<?xml version="1.0" encoding="UTF-8"?>
<movida>
  <link rel="titles" href="http://localhost:3000/api/titles"/>
  <link rel="platforms" href="http://localhost:3000/api/platforms"/>
  <link rel="title_groups" href="http://localhost:3000/api/title_groups"/>
  <link rel="schedule" href="http://localhost:3000/api/schedule"/>
  <!-- ... -->
</movida>

The only mandatory field is the name of the title group, all the rest of the fields are optional (but remember that title-group-type defaults to title_group).

So we can create a new empty title group just like this (we'll be using curl's @ option, which reads data to be posted from a file):

$ cat title_group.xml 
<title-group>
  <name>The Best War Movies</name>
</title-group>
$ curl -u robot:yourpassword --digest -H "Content-Type: application/xml" -X POST -d @title_group.xml "http://movida.example.com/api/title_groups"
<?xml version="1.0" encoding="UTF-8"?>
<title-group>
  <id type="integer">4</id>
  <name>The Best War Movies</name>
  <external-id nil="true"></external-id>
  <title-group-type>title_group</title-group-type>
  <tags></tags>
  <link rel="titles" href="http://movida.example.com/api/title_groups/4/titles"/>
  <link rel="schedule" href="http://movida.example.com/api/title_groups/4/schedule"/>
  <link rel="self" href="http://movida.example.com/api/title_groups/4"/>
  <link rel="metadata" href="http://movida.example.com/api/title_groups/4/metadata"/>
  <link rel="images" href="https://movida.example.com/api/title_groups/4/images"/>
</title-group>

In the case of a series, we just need to add the proper type:

$ cat series.xml 
<title-group>
  <name>IT Crowd</name>
  <title-group-type>series</title-group-type>
</title-group>
$ curl -u robot:yourpassword --digest -H "Content-Type: application/xml" -X POST -d @series.xml "http://movida.example.com/api/title_groups"
<?xml version="1.0" encoding="UTF-8"?>
<title-group>
  <id type="integer">6</id>
  <name>IT Crowd</name>
  <external-id nil="true"></external-id>
  <title-group-type>series</title-group-type>
  <season-number>1</season-number>
  <tags></tags>
  <link rel="titles" href="http://movida.example.com/api/title_groups/6/titles"/>
  <link rel="schedule" href="http://movida.example.com/api/title_groups/6/schedule"/>
  <link rel="self" href="http://movida.example.com/api/title_groups/6"/>
  <link rel="metadata" href="http://movida.example.com/api/title_groups/6/metadata"/>
  <link rel="images" href="http://movida.example.com/api/title_groups/6/images"/>
</title-group>

Creating series with episodes

In the case of a series, you can include the episodes and create them all together with the series. It can be done in a similar fashion to expanding the titles link when fetching a series:

$ cat series.xml
<title-group>
  <name>IT Crowd</name>
  <title-group-type>series</title-group-type>
  <external-id>12300000</external-id>
  <season-number>1</season-number>
  <link rel="titles">
    <titles type="array">
      <title>
        <name>Episode 1</name>
        <episode-number>1</episode-number>
        <external-id>12300001</external-id>
        <title-type>episode</title-type>
      </title>
      <title>
        <name>Episode 2</name>
        <episode-number>2</episode-number>
        <external-id>12300002</external-id>
        <title-type>episode</title-type>
      </title>
      <title>
        <name>Episode 3</name>
        <episode-number>3</episode-number>
        <external-id>12300003</external-id>
        <title-type>episode</title-type>
      </title>
    </titles>
  </link>
</title-group>
$ curl -u robot:yourpassword --digest -H "Content-Type: application/xml" -X POST -d @series.xml "http://movida.example.com/api/title_groups?expand=titles"
<?xml version="1.0" encoding="UTF-8"?>
<title-group>
  <id type="integer">9</id>
  <name>IT Crowd</name>
  <external-id>12300000</external-id>
  <title-group-type>series</title-group-type>
  <season-number>1</season-number>
  <tags></tags>
  <link rel="titles" href="http://movida.example.com/api/title_groups/9/titles">
    <titles type="array">
      <title>
        <id type="integer">13</id>
        <title>E01, Episode 1</title>
        <name>Episode 1</name>
        <episode-number type="integer">1</episode-number>
        <external-id>12300001</external-id>
        <title-type>episode</title-type>
        <tags></tags>
        <link rel="schedule" href="http://movida.example.com/api/titles/13/schedule"/>
        <link rel="series" href="http://movida.example.com/api/title_groups/9"/>
        <link rel="licensor" href="http://movida.example.com/api/licensors/3"/>
        <link rel="self" href="http://movida.example.com/api/titles/13"/>
        <link rel="images" href="http://movida.example.com/api/titles/13/images"/>
        <link rel="metadata" href="http://movida.example.com/api/titles/13/metadata"/>
      </title>
      <title>
        <id type="integer">14</id>
        <title>E02, Episode 2</title>
        <name>Episode 2</name>
        <episode-number type="integer">2</episode-number>
        <external-id>12300002</external-id>
        <tags></tags>
        <link rel="schedule" href="http://movida.example.com/api/titles/14/schedule"/>
        <link rel="series" href="http://movida.example.com/api/title_groups/9"/>
        <link rel="licensor" href="http://movida.example.com/api/licensors/3"/>
        <link rel="self" href="http://movida.example.com/api/titles/14"/>
        <link rel="images" href="http://movida.example.com/api/titles/14/images"/>
        <link rel="metadata" href="http://movida.example.com/api/titles/14/metadata"/>
      </title>
      <title>
        <id type="integer">15</id>
        <title>E03, Episode 3</title>
        <name>Episode 3</name>
        <episode-number type="integer">3</episode-number>
        <external-id>12300003</external-id>
        <title-type>episode</title-type>
        <tags></tags>
        <link rel="schedule" href="http://movida.example.com/api/titles/15/schedule"/>
        <link rel="series" href="http://movida.example.com/api/title_groups/9"/>
        <link rel="licensor" href="http://movida.example.com/api/licensors/3"/>
        <link rel="self" href="http://movida.example.com/api/titles/15"/>
        <link rel="images" href="http://movida.example.com/api/titles/15/images"/>
        <link rel="metadata" href="http://movida.example.com/api/titles/15/metadata"/>
      </title>
    </titles>
  </link>
  <link rel="schedule" href="http://movida.example.com/api/title_groups/9/schedule"/>
  <link rel="self" href="http://movida.example.com/api/title_groups/9"/>
  <link rel="metadata" href="http://movida.example.com/api/title_groups/9/metadata"/>
  <link rel="images" href="http://movida.example.com/api/title_groups/9/images"/>
</title-group>

Updating and deleting title groups

As our Introduction and Conventions suggests, you can update and delete title groups issuing PUT and DELETE requests to each title groups URL:

$ cat series.xml 
<title-group>
  <name>IT Crowd Season 1</name>
</title-group>
$ curl -u robot:yourpassword --digest -H "Content-Type: application/xml" -X PUT -d @series.xml "http://movida.example.com/api/title_groups/9"
<?xml version="1.0" encoding="UTF-8"?>
<title-group>
  <id type="integer">9</id>
  <name>IT Crowd Season 1</name>
  <external-id>12300000</external-id>
  <title-group-type>series</title-group-type>
  <season-number>1</season-number>
  <tags></tags>
  <link rel="titles" href="http://movida.example.com/api/title_groups/9/titles"/>
  <link rel="schedule" href="http://movida.example.com/api/title_groups/9/schedule"/>
  <link rel="self" href="http://movida.example.com/api/title_groups/9"/>
  <link rel="metadata" href="http://movida.example.com/api/title_groups/9/metadata"/>
  <link rel="images" href="http://movida.example.com/api/title_groups/9/images"/>
</title-group>
$ curl -u robot:yourpassword --digest -H "Content-Type: application/xml" -X DELETE "http://movida.example.com/api/title_groups/9"

If the type of the Title Group removed is series, then associated episodes will also be removed.

Series and Brands

Series (i.e. Title Groups where title_group_type=series) can optionally belong to a Brand. This is how a Series belonging to a Brand will look like in the API:

<?xml version="1.0" encoding="UTF-8"?>
<title-group>
  <id type="integer">9</id>
  <name>IT Crowd Season 1</name>
  <external-id>12300000</external-id>
  <title-group-type>series</title-group-type>
  <season-number>1</season-number>
  <tags></tags>
  <link rel="brand" href="http://movida.example.com/api/brands/123"/>
  <link rel="titles" href="http://movida.example.com/api/title_groups/9/titles"/>
  <link rel="schedule" href="http://movida.example.com/api/title_groups/9/schedule"/>
  <link rel="self" href="http://movida.example.com/api/title_groups/9"/>
  <link rel="metadata" href="http://movida.example.com/api/title_groups/9/metadata"/>
  <link rel="images" href="http://movida.example.com/api/title_groups/9/images"/>
</title-group>

Note the additional link rel="brand" only present when the Title Group is a Series belonging to a Brand.

You can make a Series belong to a Brand using the API just by including the link rel="brand" pointing to an existing Brand when you create or update the Title Group as described earlier in this page. Alternatively, if you create the Title Group by POSTing the XML representation of a Series to the link rel="series" of an existing Brand, then the new Series created will belong to that Brand.

Add a custom footer
Add a custom sidebar
Clone this wiki locally