We use cookies (just for analytics) on this website. If you continue we will assume you are happy with it. ok

BeBanjo

Back to index

Introduction to the Movida API

Our products have well designed, powerful, but simple web service Application Programming Interfaces. Everything a human can do in Movida can be achieved using the API.

Movida can be fully integrated into our customers media operations through its API, working seamlessly with other systems such as linear scheduling systems, media asset management or advertising campaign managers. Deep integration like this enables Movida to show our users the results of work initiated in other systems or to drive work in those systems.

As explained in the introduction to REST APIs guide, the Movida API follows the REST principles as much as possible. It is XML over HTTP using all four verbs (GET, POST, PUT, DELETE). Each resource, like series, title or scheduling, has its own URL and can be manipulated in isolation. XML responses will carry the necessary URLs to access sub-resources, so that API clients can discover resources without having to store or concatenate URLs.

Diagram

Discovering Movida Resources

Movida’s API is auto-discoverable. This means that if you start from the root, you should be able to make your way through all of the available resources:

$ curl --digest -u robot_login https://movida.bebanjo.net/api

Since currently the API only deals with scheduling information, it should return something like:

<?xml version='1.0' encoding='utf-8' ?>
<movida>
  <link rel="titles" href="https://movida.bebanjo.net/api/titles"/>
  <link rel="title_groups" href="https://movida.bebanjo.net/api/title_groups"/>
  <link rel="platforms" href="https://movida.bebanjo.net/api/platforms"/>
  <link rel="licensors" href="https://movida.bebanjo.net/api/licensors"/>
  <link rel="events" href="https://movida.bebanjo.net/api/events"/>
  <link rel="outlets" href="https://movida.bebanjo.net/api/outlets"/>
  <link rel="brands" href="https://movida.bebanjo.net/api/brands"/>
  <link rel="requirements" href="https://movida.bebanjo.net/api/requirements"/>
  <link rel="deals" href="https://movida.bebanjo.net/api/deals"/>
  <link rel="assets" href="https://movida.bebanjo.net/api/assets"/>
  <link rel="renditions" href="https://movida.bebanjo.net/api/renditions"/>
  <link rel="rights" href="https://movida.bebanjo.net/api/rights"/>
  <link rel="blackouts" href="https://movida.bebanjo.net/api/blackouts"/>
</movida>

Oh, look! There are platforms. Let’s see what that rel=platforms link tells us if we follow the href:

$ curl --digest -u robot_login https://movida.bebanjo.net/api/platforms
<?xml version='1.0' encoding='utf-8' ?>
<platforms type='array'>
  <platform>
    <name>BeBanjo Movies</name>
    <link href="https://movida.bebanjo.net/api/platforms/1/schedule" rel="schedule"></link>
  </platform>
  <platform>
    <name>YouTube</name>
    <link href="https://movida.bebanjo.net/api/platforms/2/schedule" rel="schedule"></link>
  </platform>
</platforms>

How about that? A list of platforms! Let’s now see what the schedule of YouTube looks like:

$ curl --digest -u robot_login https://movida.bebanjo.net/api/platforms/2/schedule
<?xml version='1.0' encoding='utf-8' ?>
<schedule>
  <link href="https://movida.bebanjo.net/api/platforms/2/schedule/schedulings" rel="schedulings"></link>
  <link href="https://movida.bebanjo.net/api/platforms/2" rel="platform"></link>
</schedule>

Interesting… since the schedule resource belongs to a platform, it also gives me the link to its parent resource. That could come in handy if I normally access the schedule directly and I need to access the platform for whatever reason. Let’s look at the schedulings.

$ curl --digest -u robot_login https://movida.bebanjo.net/api/platforms/2/schedule/schedulings
<?xml version='1.0' encoding='utf-8' ?>
<schedulings type='array'>
  <scheduling>
    <id type='integer'>1</id>
    <put-up type='datetime'>2009-12-15T06:00:00Z</put-up>
    <take-down type='datetime'>2010-12-15T06:00:00Z</take-down>
    <scheduling-type>catchup</scheduling-type>
    <link href="https://movida.bebanjo.net/api/title_groups/1" rel="title_group"></link>
    <link href="https://movida.bebanjo.net/api/titles/1" rel="title"></link>
    <link href="https://movida.bebanjo.net/api/schedulings/1/assets" rel="assets"></link>
  </scheduling>
  <scheduling>
    <id type='integer'>2</id>
    <put-up type='datetime'>2009-12-15T11:45:00Z</put-up>
    <take-down type='datetime'>2010-12-15T11:45:00Z</take-down>
    <scheduling-type>catchup</scheduling-type>
    <link href="https://movida.bebanjo.net/api/title_groups/18" rel="title_group"></link>
    <link href="https://movida.bebanjo.net/api/titles/18" rel="title"></link>
    <link href="https://movida.bebanjo.net/api/schedulings/2/assets" rel="assets"></link>
  </scheduling>
</schedulings>

Ta-daaa… The schedulings are all the items that compose a VoD schedule. You can see that you have the links to access both the title they belong to and the TitleGroup that they belong to. You can continue like this ad-infinitum, as long as there are related resources to dig into.

Of course, you don’t have to (in fact, you shouldn’t) start from the beginning every time. If you know you only need to access the schedulings of a particular platform, you can just go straight to that URL. If you need to remember a specific resource (like a scheduling, or a platform), we encourage you to store its URL as its unique ID, rather than the ID itself.

The expand me some nodes trick

Note: Only those resources/links that support the expand option will be highlighted in the documentation. Unless otherwise note in the docs, it should be assumed that any given resource or link doesn’t support this functionality. If you are interested in use that option with a specific resource that currently doesn’t support it please contact us.

If you get a long schedule and you then need to issue a call to each and every one of them to learn about the title or the series they belong to, it can become a bit cumbersome. That is why we use the ‘expand’ parameter. We were inspired by this very same trick (stole it) in the Netflix API, and we love it.

Let’s say that in the previous example you wanted to see, along with the schedulings, the information about the titles that they belong to.

Instead of:

$ curl --digest -u robot_login https://movida.bebanjo.net/api/platforms/2/schedule/schedulings

Try:

$ curl --digest -u robot_login https://movida.bebanjo.net/api/platforms/2/schedule/schedulings?expand=title

Lo and behold!

<?xml version='1.0' encoding='utf-8' ?>
<schedulings type='array'>
  <scheduling>
    <id type='integer'>1</id>
    <put-up type='datetime'>2009-12-15T06:00:00Z</put-up>
    <take-down type='datetime'>2010-12-15T06:00:00Z</take-down>
    <scheduling-type>catchup</scheduling-type>
    <link href="https://movida.bebanjo.net/api/title_groups/1" rel="title_group"></link>
    <link href="https://movida.bebanjo.net/api/titles/1" rel="title">
      <title>
        <id type='integer'>1</id>
        <name>E01, No title</name>
        <external-id>C5080530001</external-id>
        <title-type>episode</title-type>
        <link href="https://movida.bebanjo.net/api/titles/1/schedule" rel="schedule"></link>
        <link href="https://movida.bebanjo.net/api/title_groups/1" rel="series"></link>
        <link href="https://movida.bebanjo.net/api/licensors/103" rel="licensor"></link>
        <link href="https://movida.bebanjo.net/api/titles/1/metadata" rel="metadata"></link>
      </title>
    </link>
  </scheduling>
  ...
</schedulings>

See what it is doing? The API will look for all of the link elements that have a rel="title" (the parameter you passed), and return inside all of the link elements exactly what you would get if you were to call that title URL individually. This allows you to save some time and decide, depending on whether you want less or more information, whether you want to use expand or not.

What if you wanted to get both the title and the title group information? Easy peasy:

$ curl --digest -u robot_login https://movida.bebanjo.net/api/platforms/2/schedule/schedulings?expand=title,title_group

I insist, lo and behold!

<?xml version='1.0' encoding='utf-8' ?>
<schedulings type='array'>
  <scheduling>
    <id type='integer'>1</id>
    <put-up type='datetime'>2009-12-15T06:00:00Z</put-up>
    <take-down type='datetime'>2010-12-15T06:00:00Z</take-down>
    <scheduling-type>catchup</scheduling-type>
    <link href="https://movida.bebanjo.net/api/title_groups/1" rel="title_group">
      <title-group>
        <id type='integer'>1</id>
        <name>Sopranos, S01</name>
        <external-id>08053</external-id>
        <title-group-type>series</title-group-type>
        <season-number>1</season-number>
        <link href="https://movida.bebanjo.net/api/title_groups/1/titles" rel="titles"></link>
        <link href="https://movida.bebanjo.net/api/title_groups/1/schedule" rel="schedule"></link>
        <link href="https://movida.bebanjo.net/api/title_groups/1/metadata" rel="metadata"></link>
      </title-group>
    </link>
    <link href="https://movida.bebanjo.net/api/titles/1" rel="title">
      <title>
        <id type='integer'>1</id>
        <name>E01, No title</name>
        <external-id>C5080530001</external-id>
        <title-type>episode</title-type>
        <link href="https://movida.bebanjo.net/api/titles/1/schedule" rel="schedule"></link>
        <link href="https://movida.bebanjo.net/api/title_groups/1" rel="series"></link>
        <link href="https://movida.bebanjo.net/api/licensors/103" rel="licensor"></link>
        <link href="https://movida.bebanjo.net/api/titles/1/metadata" rel="metadata"></link>
      </title>
    </link>
  </scheduling>
  ...
</schedulings>

Now you have expanded both the title and the title group.

You might be asking yourself… and what exactly is a title_group? You can find out on its resource page, but first have a look at the following diagram, which shows the currently API accessible resources and how you can navigate between them:

Resources

As you can see, you can access the schedule of a platform, but also the schedule of a particular title or title_group, and each of those schedules can have a specific set of schedulings, which are essentially the period of time when a title is scheduled in a particular platform.

Last updated May 05th, 2017.