Skip to content

Movida Resource: Blackout

Jump to bottom Edit New page
Fernando Blat edited this page Jul 3, 2014 · 13 revisions

this resource is not available yet in the API

Introduction

Movida Blackouts represent the time window in which a content can´t be displayed. They apply on a feature or a series.

This is how a Movida Blackout looks like:

<blackout>
  <id type="integer">4</id>
  <reason>Missing rights</reason>
  <from type="datetime">2010-10-10</from>
  <to type="datetime">2011-10-10</to>
  <episode-selection-type>except</episode-selection-type>
  <episode-selection>1,7-9</episode-selection>
  <link rel="self" href="https://movida.example.com/api/blackouts/4"/>
  <link rel="licensable" href="http://movida.example.com/api/title_groups/1"/>
  <link rel="granted_requirements" href="http://movida.example.com/api/blackouts/4/granted_requirements"/>
</blackout>

Blackout attributes

  • id (mandatory): Movida internal identifier of the blackout.
  • from (mandatory): a date timestamp representing when the blackout starts.
  • to (mandatory): a date timestamp representing when the blackout ends.
  • episode-selection-type (optional): this attribute only makes sense for blackouts defined on series. Can take three different values:
    • all: the blackout applies to all episodes in the series.
    • only: the blackout applies to the episode specified in the attribute <episode-selection>.
    • except: the blackout applies to all episodes except those specified in the attribute <episode-selection>.
  • episode-selection (optional): this attribute only makes sense when <episode-selection-type> has the values only or except. Its purpose is to specify a range of episodes, separating the episode numbers by commas or by a dash. A dash range means that all the episodes in that range are included. For example:
    • 1,3-5,7,9 range includes the episodes 1, 3, 4, 5, 7 and 9
    • 1-3,9,11-13 range includes the episodes 1, 2, 3, 9, 11, 12 and 13

Get a list of blackouts from a licensable

We´ll be fetching the blackouts from a series, but this is also applicable for titles.

Given an existing Series, for example:

<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>
  <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>

All the blackouts of that title group can be obtained by following the link rel="blackouts":

curl --digest -u robot_user https://movida.example.com/api/title_groups/180/blackouts
<blackouts type="array">
  <blackout>
    <id type="integer">4</id>
    <reason>Missing rights</reason>
    <from type="datetime">2010-10-10</from>
    <to type="datetime">2011-10-10</to>
    <episode-selection-type>except</episode-selection-type>
    <episode-selection>1,7-9</episode-selection>
    <link rel="self" href="https://movida.example.com/api/blackouts/4"/>
    <link rel="licensable" href="http://movida.example.com/api/title_groups/180"/>
    <link rel="granted_requirements" href="http://movida.example.com/api/blackouts/4/granted_requirements"/>
  </blackout>
  <blackout>
    <id type="integer">5</id>
    <reason>Missing rights</reason>
    <from type="datetime">2012-10-10</from>
    <to type="datetime">2013-10-10</to>
    <episode-selection-type>all</episode-selection-type>
    <link rel="self" href="https://movida.example.com/api/blackouts/5"/>
    <link rel="licensable" href="http://movida.example.com/api/title_groups/180"/>
    <link rel="granted_requirements" href="http://movida.example.com/api/blackouts/5/granted_requirements"/>
  </blackout>
</blackouts>

Get a single blackout

Just do a GET to the URI of the Blackout (the one in the attribute rel="self"):

curl --digest -u robot_user https://movida.example.com/api/blackouts/5
<blackout>
  <id type="integer">5</id>
  <reason>Missing rights</reason>
  <from type="datetime">2012-10-10</from>
  <to type="datetime">2013-10-10</to>
  <episode-selection-type>all</episode-selection-type>
  <link rel="self" href="https://movida.example.com/api/blackouts/5"/>
  <link rel="licensable" href="http://movida.example.com/api/title_groups/180"/>
  <link rel="granted_requirements" href="http://movida.example.com/api/blackouts/5/granted_requirements"/>
</blackout>

Getting the list of granted requirements of a blackout

We´ll be fetching blackout granted requirements by following the link rel="granted_requirements":

curl --digest -u robot_user http://movida.example.com/api/blackouts/6/granted_requirements
<granted_requirements type="array">
  <granted_requirement>
    <link rel="requirement" href="http://movida.example.com/api/requirements/2"/>
  </granted_requirement>
</granted_requirements>

Creating blackouts

To create a blackout, you just need to POST a proper XML Blacktout representation to the blackouts URL of a given title group or title. As explained above, that URL is in the link node whose 'rel' attribute equals 'blackouts'.

For example, the following XML issued as a POST to the blackouts URL of a title would create a blackout (we’ll use curl’s @ option, which reads data to be posted from a file):

cat blackout.xml
<blackout>
  <from type="datetime">2010-10-10</from>
  <to type="datetime">2011-10-10</to>
  <episode-selection-type>except</episode-selection-type>
  <episode-selection>1,3</episode-selection>
  <link rel="licensable" href="http://movida.example.com/api/title_groups/1"/>
</blackout>
curl --digest -u robot_user:password -H "Content-Type: application/xml" -X POST -d @blackout.xml "https://movida.example.com/api/title_groups/1/blackouts"

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

<blackout>
  <id type="integer">6</id>
  <from type="datetime">2010-10-10</from>
  <to type="datetime">2011-10-10</to>
  <episode-selection-type>except</episode-selection-type>
  <episode-selection>1,3</episode-selection>
  <link rel="self" href="http://movida.example.com/api/blackouts/6"/>
  <link rel="licensable" href="http://movida.example.com/api/title_groups/1"/>
  <link rel="granted_requirements" href="http://movida.example.com/api/blackouts/6/granted_requirements"/>
</blackout>

Updating blackouts

As our Introduction and Conventions page suggests, you can update a blackout issuing a PUT request to each blackout URI:

cat blackout_update.xml
<blackout>
  <episode-selection-type>only</episode-selection-type>
  <episode-selection>1,2</episode-selection>
</blackout>
curl --digest -u robot_user:password -H "Content-Type: application/xml" -X PUT -d @blackout_update.xml "https://movida.example.com/api/blackouts/13"

As always Movida will return the full XML of the blackout just updated:

<?xml version="1.0" encoding="UTF-8"?>
<blackout>
  <id type="integer">13</id>
  <reason>Missing rights</reason>
  <from type="datetime">2012-10-10</from>
  <to type="datetime">2013-10-10</to>
  <episode-selection-type>only</episode-selection-type>
  <episode-selection>1,2</episode-selection>
  <link rel="self" href="https://movida.example.com/api/blackouts/13"/>
  <link rel="licensable" href="http://movida.example.com/api/title_groups/180"/>
  <link rel="granted_requirements" href="http://movida.example.com/api/blackouts/13/granted_requirements"/>
</blackout>

Updating blackout granted requirements

In order to apply the blackout to one or many requirements, a new PUT request needs to be performed to the link identified by a 'rel' attribute equals to 'granted_requirements' with the complete list of granted requirements the blackout applies to.

For example, the following XML issued as a PUT to the granted requirements URL of a blackout will grant a requirement to it:

cat requirement.xml
<granted_requirements type="array">
  <granted_requirement>
    <link rel="requirement" href="http://movida.example.com/api/requirements/3"/>
  </granted_requirement>
  <granted_requirement>
    <link rel="requirement" href="http://movida.example.com/api/requirements/2"/>
  </granted_requirement>
</granted_requirements>
curl --digest -u robot_user:password -H "Content-Type: application/xml" -X PUT -d @requirement.xml "https://movida.example.com/api/blackouts/6/granted_requirements"

Movida will return the full XML of the granted requirement just created:

<granted_requirements type="array">
  <granted_requirement>
    <link rel="requirement" href="http://movida.example.com/api/requirements/3"/>
  </granted_requirement>
  <granted_requirement>
    <link rel="requirement" href="http://movida.example.com/api/requirements/2"/>
  </granted_requirement>
</granted_requirements>

Deleting blackouts

Also you can delete a blackout using DELETE request to each blackout URI:

curl --digest -u robot_user:password -X DELETE "https://movida.example.com/api/blackouts/33"

The DELETE request doesn’t return anything, as that blackout is now gone.

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