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 REST APIs

Movida, Metadata and Sequence APIs are based on REST principles.

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

Basic principles

In short, our APIs follow these principles:

  1. Communication is done over HTTPS.
  2. Each resource has its own URL, which you use to interact with it.
  3. Interaction is done using the basic HTTP verbs:
    • GET for fetching resources
    • POST for creating resources
    • PUT for updating resources
    • DELETE for deleting resources
  4. The format used is XML following some conventions. POST and PUT requests require valid XML and properly escaped node contents.
  5. Each resource is linked with related resources using the <link> tag and its URLs.

Conventions

BeBanjo’s APIs currently return XML and setting an Accept: application/xml header in any request made to the APIs is required.

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.

<?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="http://movida.bebanjo.net/api/title_groups/1" rel="title_group"></link>
    <link href="http://movida.bebanjo.net/api/titles/1" rel="title"></link>
  </scheduling>
  <scheduling>
    ...
  </scheduling>
</schedulings>

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.

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 representation of the resource that follows the same conventions as described above (i.e. the same XML that you fetch with a GET should work with a PUT). It’s also required for these operations the inclusion of a Content-Type: application/xml header. Here is an example of a POST cURL request:

$ cat title.xml
<title>
  <name>13 Assassins</name>
  <external-id>123456</external-id>
  <link rel="licensor" href="http://movida.bebanjo.net/api/licensors/4"/>
</title>
$ curl -u robot:yourpassword --digest -H "Content-Type: application/xml" -X POST -d @title.xml "http://movida.bebanjo.net/api/titles"

Autodiscovery

Our APIs are auto-discoverable. This means that if you start from the root of either Sequence or Movida, 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 Movida, 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.

Further reading

If you are looking for a deeper understanding of REST, try the following resources:

A good introduction to many of the principles and ideas we follow when designing our APIs are outlined in these blog posts:

Last updated July 07th, 2017.