-
Notifications
You must be signed in to change notification settings - Fork 6
Movida Resource: Blackout
this resource is not available yet in the API
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="date">2010-10-10</from>
<to type="date">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>
- 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 valuesonly
orexcept
. 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
-
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="date">2010-10-10</from>
<to type="date">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="date">2012-10-10</from>
<to type="date">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>
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="date">2012-10-10</from>
<to type="date">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>
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>
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="date">2010-10-10</from>
<to type="date">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="date">2010-10-10</from>
<to type="date">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>
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="date">2012-10-10</from>
<to type="date">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>
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>
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.