Skip to content

Developers

How can we help you?

← Go back

Introduction to the BeBanjo API

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

BeBanjo 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 BeBanjo 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 BeBanjo API follows the REST principles as much as possible. It is XML/JSON 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/JSON 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 BeBanjo Resources

BeBanjo’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_user:password https://movida.bebanjo.net/api

$ curl --digest -u robot_user:password -H "Accept: application/json" 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="brands" href="https://movida.bebanjo.net/api/brands"/>
  <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="linear_channels" href="https://movida.bebanjo.net/api/linear_channels"/>
  <link rel="deals" href="https://movida.bebanjo.net/api/deals"/>
  <link rel="images" href="https://movida.bebanjo.net/api/images"/>
  <link rel="assets" href="https://movida.bebanjo.net/api/assets"/>
  <link rel="requirements" href="https://movida.bebanjo.net/api/requirements"/>
  <link rel="contributors" href="https://movida.bebanjo.net/api/contributors"/>
  <link rel="credit_roles" href="https://movida.bebanjo.net/api/credit_roles"/>
  <link rel="renditions" href="https://movida.bebanjo.net/api/renditions"/>
  <link rel="rights" href="https://movida.bebanjo.net/api/rights"/>
  <link rel="denied_rights" href="https://movida.bebanjo.net/api/denied_rights"/>
  <link rel="rules" href="https://movida.bebanjo.net/api/rules"/>
  <link rel="blackouts" href="https://movida.bebanjo.net/api/blackouts"/>
  <link rel="schedulings" href="https://movida.bebanjo.net/api/schedule/schedulings"/>
  <link rel="enumerations" href="https://movida.bebanjo.net/api/enumerations"/>
</movida>

{
  "resource_type": "movida",
  "titles_link": "https://movida.bebanjo.net/api/titles",
  "title_groups_link": "https://movida.bebanjo.net/api/title_groups",
  "brands_link": "https://movida.bebanjo.net/api/brands",
  "platforms_link": "https://movida.bebanjo.net/api/platforms",
  "licensors_link": "https://movida.bebanjo.net/api/licensors",
  "events_link": "https://movida.bebanjo.net/api/events",
  "outlets_link": "https://movida.bebanjo.net/api/outlets",
  "linear_channels_link": "https://movida.bebanjo.net/api/linear_channels",
  "deals_link": "https://movida.bebanjo.net/api/deals",
  "images_link": "https://movida.bebanjo.net/api/images",
  "assets_link": "https://movida.bebanjo.net/api/assets",
  "requirements_link": "https://movida.bebanjo.net/api/requirements",
  "contributors_link": "https://movida.bebanjo.net/api/contributors",
  "credit_roles_link": "https://movida.bebanjo.net/api/credit_roles",
  "renditions_link": "https://movida.bebanjo.net/api/renditions",
  "rights_link": "https://movida.bebanjo.net/api/rights",
  "denied_rights_link": "https://movida.bebanjo.net/api/denied_rights",
  "rules_link": "https://movida.bebanjo.net/api/rules",
  "blackouts_link": "https://movida.bebanjo.net/api/blackouts",
  "schedulings_link": "https://movida.bebanjo.net/api/schedule/schedulings",
  "enumerations_link": "https://movida.bebanjo.net/api/enumerations"
}

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

$ curl --digest -u robot_user:password https://movida.bebanjo.net/api/platforms

$ curl --digest -u robot_user:password -H "Accept: application/json" https://movida.bebanjo.net/api/platforms

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

{
  "entries": [
    {
      "resource_type": "platform",
      "id": 1,
      "name": "BeBanjo Movies",
      "self_link": "https://movida.bebanjo.net/api/platforms/1",
      "schedule_link": "https://movida.bebanjo.net/api/platforms/1/schedule"
    },
    {
      "resource_type": "platform",
      "id": 2,
      "name": "YouTube",
      "self_link": "https://movida.bebanjo.net/api/platforms/2",
      "schedule_link": "https://movida.bebanjo.net/api/platforms/2/schedule"
    }
  ]
}

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

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

$ curl --digest -u robot_user:password -H "Accept: application/json" https://movida.bebanjo.net/api/platforms/2/schedule

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

{
  "resource_type": "schedule",
  "schedulings_link": "https://movida.bebanjo.net/api/platforms/2/schedule/schedulings",
  "platform_link": "https://movida.bebanjo.net/api/platforms/2"
}

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_user:password https://movida.bebanjo.net/api/platforms/2/schedule/schedulings

$ curl --digest -u robot_user:password -H "Accept: application/json" 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 rel="title_group" href="https://movida.bebanjo.net/api/title_groups/1"/>
    <link rel="title" href="https://movida.bebanjo.net/api/titles/1"/>
    <link rel="assets" href="https://movida.bebanjo.net/api/assets/1"/>
  </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 rel="title_group" href="https://movida.bebanjo.net/api/title_groups/18"/>
    <link rel="title" href="https://movida.bebanjo.net/api/titles/18"/>
    <link rel="assets" href="https://movida.bebanjo.net/api/assets/18"/>
  </scheduling>
</schedulings>

{
  "entries": [
    {
      "resource_type": "scheduling",
      "id": 1,
      "put_up": "2009-12-15T06:00:00Z",
      "take_down": "2010-12-15T06:00:00Z",
      "scheduling_type": "catchup",
      "self_link": "https://movida.bebanjo.net/api/schedulings/1",
      "title_group_link": "https://movida.bebanjo.net/api/title_groups/1",
      "title_link": "https://movida.bebanjo.net/api/titles/1",
      "asset_link": "https://movida.bebanjo.net/api/assets/1"
    },
    {
      "resource_type": "scheduling",
      "id": 2,
      "put_up": "2009-12-15T11:45:00Z",
      "take_down": "2010-12-15T11:45:00Z",
      "scheduling_type": "catchup",
      "self_link": "https://movida.bebanjo.net/api/schedulings/2",
      "title_group_link": "https://movida.bebanjo.net/api/title_groups/18",
      "title_link": "https://movida.bebanjo.net/api/titles/18",
      "asset_link": "https://movida.bebanjo.net/api/assets/18"
    }
  ]
}

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_user:password https://movida.bebanjo.net/api/platforms/2/schedule/schedulings

$ curl --digest -u robot_user:password -H "Accept: application/json" https://movida.bebanjo.net/api/platforms/2/schedule/schedulings

Try:

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

$ curl --digest -u robot_user:password -H "Accept: application/json" 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 rel="title_group" href="https://movida.bebanjo.net/api/title_groups/1"/>
    <link rel="title" href="https://movida.bebanjo.net/api/titles/1">
      <title>
        <id type='integer'>1</id>
        <name>E01, No title</name>
        <external-id>C5080530001</external-id>
        <title-type>episode</title-type>
        <link rel="schedule" href="https://movida.bebanjo.net/api/titles/1/schedule"/>
        <link rel="series" href="https://movida.bebanjo.net/api/title_groups/1"/>
        <link rel="licensor" href="https://movida.bebanjo.net/api/licensors/103"/>
        <link rel="metadata" href="https://movida.bebanjo.net/api/titles/1/metadata"/>
      </title>
    </link>
  </scheduling>
  ...
</schedulings>

{
  "entries": [
    {
      "resource_type": "scheduling",
      "id": 1,
      "put_up": "2009-12-15T06:00:00Z",
      "take_down": "2010-12-15T06:00:00Z",
      "scheduling_type": "catchup",
      "self_link": "https://movida.bebanjo.net/api/schedulings/1",
      "title_group_link": "https://movida.bebanjo.net/api/title_groups/1",
      "title_link": "https://movida.bebanjo.net/api/titles/1",
      "title": {
        "resource_type": "title",
        "id": 1,
        "name": "E01, No title",
        "external_id": "C5080530001",
        "title_type": "episode",
        "self_link": "https://movida.bebanjo.net/api/titles/1",
        "schedule_link": "https://movida.bebanjo.net/api/titles/1/schedule",
        "series_link": "https://movida.bebanjo.net/api/title_groups/1",
        "licensor_link": "https://movida.bebanjo.net/api/licensors/103",
        "metadata_link": "https://movida.bebanjo.net/api/titles/1/metadata"
      }
    },
    // ...
  ]
}

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_user:password https://movida.bebanjo.net/api/platforms/2/schedule/schedulings?expand=title,title_group

$ curl --digest -u robot_user:password -H "Accept: application/json" 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 rel="title_group" href="https://movida.bebanjo.net/api/title_groups/1">
      <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>
        <season-reference-id>Winter</season-reference-id>
        <link rel="titles" href="https://movida.bebanjo.net/api/title_groups/1/titles"/>
        <link rel="schedule" href="https://movida.bebanjo.net/api/title_groups/1/schedule"/>
        <link rel="metadata" href="https://movida.bebanjo.net/api/title_groups/1/metadata"/>
      </title-group>
    </link>
    <link rel="title" href="https://movida.bebanjo.net/api/titles/1">
      <title>
        <id type='integer'>1</id>
        <name>E01, No title</name>
        <external-id>C5080530001</external-id>
        <title-type>episode</title-type>
        <link rel="schedule" href="https://movida.bebanjo.net/api/titles/1/schedule"/>
        <link rel="series" href="https://movida.bebanjo.net/api/title_groups/1"/>
        <link rel="licensor" href="https://movida.bebanjo.net/api/licensors/103"/>
        <link rel="metadata" href="https://movida.bebanjo.net/api/titles/1/metadata"/>
      </title>
    </link>
  </scheduling>
  ...
</schedulings>

{
  "entries": [
    {
      "resource_type": "scheduling",
      "id": 1,
      "put_up": "2009-12-15T06:00:00Z",
      "take_down": "2010-12-15T06:00:00Z",
      "scheduling_type": "catchup",
      "self_link": "https://movida.bebanjo.net/api/schedulings/1",
      "title_group_link": "https://movida.bebanjo.net/api/title_groups/1",
      "title_group": {
        "resource_type": "title_group",
        "id": 1,
        "name": "Sopranos, S01",
        "external_id": "08053",
        "title_group_type": "series",
        "season_number": 1,
        "season_reference_id": "Winter",
        "self_link": "https://movida.bebanjo.net/api/title_groups/1",
        "titles_link": "https://movida.bebanjo.net/api/title_groups/1/titles",
        "schedule_link": "https://movida.bebanjo.net/api/title_groups/1/schedule",
        "metadata_link": "https://movida.bebanjo.net/api/title_groups/1/metadata"
      },
      "title_link": "https://movida.bebanjo.net/api/titles/1",
      "title": {
        "resource_type": "title",
        "id": 1,
        "name": "E01, No title",
        "external_id": "C5080530001",
        "title_type": "episode",
        "self_link": "https://movida.bebanjo.net/api/titles/1",
        "schedule_link": "https://movida.bebanjo.net/api/titles/1/schedule",
        "series_link": "https://movida.bebanjo.net/api/title_groups/1",
        "licensor_link": "https://movida.bebanjo.net/api/licensors/103",
        "metadata_link": "https://movida.bebanjo.net/api/titles/1/metadata"
      }
    },
    // ...
  ]
}

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.