Blackout
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 Blackout looks like:
<blackout>
<id type="integer">4</id>
<external-id>ext-id-004</external-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.bebanjo.net/api/blackouts/4"/>
<link rel="licensable" href="https://movida.bebanjo.net/api/title_groups/1"/>
<link rel="granted_requirements" href="https://movida.bebanjo.net/api/blackouts/4/granted_requirements"/>
</blackout>
Valid attributes
-
id
(required): Movida internal identifier of the blackout. -
external-id
(optional): An external system identifier of the blackout. -
from
(required): a date timestamp representing when the blackout starts. -
to
(required): a date timestamp representing when the blackout ends. -
episode-selection-type
(optional): this attribute only makes sense for blackouts defined on series. It 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. Can’t be longer than 255 characters. 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 all blackouts in the current account
Blackouts are linked from the root of the API, through the link identified with the rel="blackouts"
attribute:
<?xml version="1.0" encoding="UTF-8"?>
<movida>
<!-- ... -->
<link rel="blackouts" href="https://movida.bebanjo.net/api/blackouts">
</movida>
Following that link, we can fetch the list of blackouts in the current account.
$ curl --digest -u robot_user:password https://movida.bebanjo.net/api/blackouts
<?xml version="1.0" encoding="UTF-8"?>
<blackouts>
<total-entries>27</total-entries>
<blackout>
<id type="integer">5</id>
<external-id>ext-id-005</external-id>
<!-- ... -->
</blackout>
<blackout>
<id type="integer">6</id>
<external-id>ext-id-006</external-id>
<!-- ... -->
</blackout>
<!-- ... -->
<blackouts>
Note: This is a paginated resource. By default, only 50 blackouts will be included in each page but you can override this default by using the
per_page
parameter described in the next section. Thetotal-entries
attribute will indicate the total number of entries and the linksrel="next"
andrel="prev"
should be used to get the next and the previous pages.
Valid attributes
You can filter the list of blackouts returned using the following parameters:
-
external_id
: It will return only the blackout with the exact given external-id (if any). -
per_page
: Number of elements returned in each page. The maximum value allowed is 200 and the default is 50. -
page
: Number of the page you want to be returned.
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.bebanjo.net/api/title_groups/180/titles" rel="titles"></link>
<link href="https://movida.bebanjo.net/api/title_groups/180/schedule" rel="schedule"></link>
<link href="https://movida.bebanjo.net/api/title_groups/180/metadata" rel="metadata"></link>
<link href="https://movida.bebanjo.net/api/title_groups/180/images" rel="images"></link>
<link href="https://movida.bebanjo.net/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.bebanjo.net/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.bebanjo.net/api/blackouts/4"/>
<link rel="licensable" href="https://movida.bebanjo.net/api/title_groups/180"/>
<link rel="granted_requirements" href="https://movida.bebanjo.net/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.bebanjo.net/api/blackouts/5"/>
<link rel="licensable" href="https://movida.bebanjo.net/api/title_groups/180"/>
<link rel="granted_requirements" href="https://movida.bebanjo.net/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.bebanjo.net/api/blackouts/5
<blackout>
<id type="integer">5</id>
<external-id>sample-external-id-001</external-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.bebanjo.net/api/blackouts/5"/>
<link rel="licensable" href="https://movida.bebanjo.net/api/title_groups/180"/>
<link rel="granted_requirements" href="https://movida.bebanjo.net/api/blackouts/5/granted_requirements"/>
</blackout>
Creating a blackout
To create a blackout, you just need to POST
a proper XML blackout 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>
<external-id>the-blackout-id-in-your-system</external-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>
</blackout>
$ curl --digest -u robot_user:password -H "Content-Type: application/xml" -X POST -d @blackout.xml "https://movida.bebanjo.net/api/title_groups/1/blackouts"
Movida will return the full XML of the blackout just created:
<blackout>
<id type="integer">6</id>
<external-id>the-blackout-id-in-your-system</external-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="https://movida.bebanjo.net/api/blackouts/6"/>
<link rel="licensable" href="https://movida.bebanjo.net/api/title_groups/1"/>
<link rel="granted_requirements" href="https://movida.bebanjo.net/api/blackouts/6/granted_requirements"/>
</blackout>
Updating blackouts
As our introduction to REST APIs guide 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.bebanjo.net/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>
<external-id>ext-id-0013</external-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.bebanjo.net/api/blackouts/13"/>
<link rel="licensable" href="https://movida.bebanjo.net/api/title_groups/180"/>
<link rel="granted_requirements" href="https://movida.bebanjo.net/api/blackouts/13/granted_requirements"/>
</blackout>
Managing blackout’s granted requirements
In order to apply the blackout to one or many requirements, you’ll need to use the link identified by a rel
attribute equals to granted_requirements
. See the documentation of the granted requirement resource for additional information.
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.bebanjo.net/api/blackouts/33"
The DELETE
request doesn’t return anything, as that blackout is now gone.
Last updated April 20th, 2018.