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.
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:
GETfor fetching resources
POSTfor creating resources
PUTfor updating resources
DELETEfor deleting resources
- The format used is XML following some conventions.
PUTrequests require valid XML and properly escaped node contents.
- Each resource is linked with related resources using the
<link>tag and its URLs.
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:
<?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> </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
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.
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:
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.
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="https://movida.bebanjo.net/api/licensors/4"/> </title>
$ curl -u robot:yourpassword --digest -H "Content-Type: application/xml" -X POST -d @title.xml "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.
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.
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.
If you are looking for a deeper understanding of REST, try the following resources:
Richardson’s book RESTful Web Services
A good introduction to many of the principles and ideas we follow when designing our APIs are outlined in these blog posts:
Last updated October 19th, 2018.