Developers

How can we help you?

Introduction to REST APIs

Mediagenix On-Demand, Metadata and Sequence APIs are based on REST principles.

We will get you up to speed using REST with Mediagenix On-Demand applications, but if you want to dig deeper check further reading.

Basic principles

In short, our APIs follow these principles:

Communication is done over HTTPS.
Each resource has its own URL, which you use to interact with it.
Interaction is done using the basic HTTP verbs:
- GET for fetching resources
- POST for creating resources
- PUT for updating resources
- DELETE for deleting resources
XML or JSON formats are accepted following some conventions. POST and PUT requests require valid XML/JSON payloads.
Each resource is linked with related resources.

Conventions

Mediagenix On-Demand’s APIs currently return XML or JSON, based on your preference. The format can be set using the Accept header (Accept: application/xml or Accept: application/json). By default, if no header is set, XML will be returned.

XML Conventions

All XML elements returned will carry its type as an attribute, except strings. So if there is no type attribute on a node, then it is either a string or a single node with children.

Available types are: array, integer, date, datetime, duration, boolean and document.

For date and datetime types the API uses the following formats:

date: ‘YYYY-MM-DD’
datetime: ISO 8601 YYYY-MM-DDThh:mm:ssTZD, where TZD is the time zone designator (Z or +hh:mm or -hh:mm); the + or - values indicate how far ahead or behind a time zone is from the UTC (Coordinated Universal Time) zone.

We recommend the usage of the same formats when making requests to the API as those are the ones we support.

<?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"/>
  </scheduling>
  <scheduling>
    ...
  </scheduling>
</schedulings>

When making POST and PUT requests to the API, content nodes should be properly escaped.

There is always one level of depth within each resource (i.e. a “scheduling”), so that you can always find its attributes directly underneath its node. The exception is when the type is document. In this case it can hold a free form XML, which may vary in its format and depth.

Relationships with other resources are declared via the *_link tags which enables autodiscovery.

JSON Conventions

Endpoints in Mediagenix On-Demand’s APIs can return an individual resource or a collection of resources.

An individual resource will be formatted as a JSON object. Every resource object will have a resource_type key containing the type of the resource.

Relationships with other resources are declared via *_link keys which enables autodiscovery.

{
  "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"
}

A collection of resources will be formatted as a JSON object with an entries key that will contain an array of individual resources.

{
  "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"
    },
    {
      "resource_type": "scheduling",
      "id": 2,
      "put_up": "2009-12-16T06:00:00Z",
      "take_down": "2010-12-17T06:00:00Z",
      "scheduling_type": "archive",
      "self_link": "https://movida.bebanjo.net/api/schedulings/2",
      "title_group_link": "https://movida.bebanjo.net/api/title_groups/2",
      "title_link": "https://movida.bebanjo.net/api/titles/2"
    }
    // ...
  ]
}

date, datetime, duration and boolean values will be sent as strings.

For date and datetime types the API uses the following formats:

date: ‘YYYY-MM-DD’
datetime: ISO 8601 YYYY-MM-DDThh:mm:ssTZD, where TZD is the time zone designator (Z or +hh:mm or -hh:mm); the + or - values indicate how far ahead or behind a time zone is from the UTC (Coordinated Universal Time) zone.

We recommend the usage of the same formats when making requests to the API as those are the ones we support.

Operations

Each resource has its own URL, which you use to interact with it. There are 4 operations that you can use for a given URL: GET, POST, PUT and DELETE which semantics are, unsurprisingly, fetching, creating, updating or deleting the given resource.

Keep in mind that some operations might not be available for some resources. Refer to the specific application API documentation in order to know which are the available operations.

For PUT and POST operations the request must include in its body an XML/JSON representation of the resource that follows the same conventions as described above (i.e. the same XML/JSON that you fetch with a GET should work with a PUT). For these operations the inclusion of a Content-Type header (Content-Type: application/xml or Content-Type: application/json) is also required. Here is an example of a POST cURL request:

$ cat title.xml

$ cat title.json

<title>
  <name>13 Assassins</name>
  <external-id>123456</external-id>
  <link rel="licensor" href="https://movida.bebanjo.net/api/licensors/4"/>
</title>

{
  "resource_type": "title",
  "name": "13 Assassins",
  "external_id": "123456",
  "licensor_link": "https://movida.bebanjo.net/api/licensors/4"
}

$ curl --digest -u robot_user:password -H "Content-Type: application/xml" -X POST -d @title.xml "https://movida.bebanjo.net/api/titles"

$ curl --digest -u robot_user:password -H "Content-Type: application/json" -H "Accept: application/json" -X POST -d @title.json "https://movida.bebanjo.net/api/titles"

In addition to the four basic HTTP operations, conforming with the HTTP/1.1 standard, each resource responds to the HEAD method. A HEAD request is like a GET request but it only returns headers, not the body in the response.

Autodiscovery

Our APIs are auto-discoverable. This means that if you start from the root of either Sequence or Mediagenix On-Demand, you should be able to make your way through all of the available resources via the urls held in the link nodes.

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, for instance, the schedulings of a particular platform in Mediagenix On-Demand, you can just go straight to that URL; or if you have to update a particular Sequence task, you can store that URL as its unique identifier and perform an HTTP PUT to update it.

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.

Backwards compatibility

Our API is in constant evolution. Developers who use our APIs can assume their software will continue working while we add new features, provided that new nodes might be added to any of the XML representations of our API resources.

We commit to not remove information, change its format, or the way it’s accessed, unless previously agreed with all our integrators.