Almodovar¶ ↑

Almodovar is a client for BeBanjo’s Sequence & Movida API written in Ruby (it’s actually a generic client which plays nice with any RESTful API following some conventions).

Getting started¶ ↑

Install the gem (make sure you have rubygems.org in your gem source list):

$ [sudo] gem install almodovar

Now, let’s play with irb:

>> require 'almodovar'
=> true

First you need an authentication token:

>> auth = Almodovar::DigestAuth.new("realm", "user", "password")
=> #<Almodovar::DigestAuth:0x101f846c8 ... >

Now you have to instantiate a resource given its URL. Let’s try with the root of the Movida API:

>> movida = Almodovar::Resource("http://movida.example.com/api", auth)
=> <movida>
<link href="http://movida.example.com/api/titles" rel="titles"/>
<link href="http://movida.example.com/api/platforms" rel="platforms"/>
<link href="http://movida.example.com/api/title_groups" rel="title_groups"/>
</movida>

Ok. Let’s see what we have under platforms

>> movida.platforms
=> [<platform>
<name>YouTube</name>
<link href="http://movida.example.com/api/platforms/5/schedule" rel="schedule"/>
</platform>, <platform>
<name>Vimeo</name>
<link href="http://movida.example.com/api/platforms/6/schedule" rel="schedule"/>
</platform>]

Now, show me the schedule of a title given its external id:

>> movida.titles(:external_id => "C5134350003").first.schedule(:expand => :schedulings)
=> <schedule>
<link href="http://staging.schedule.bebanjo.net/api/titles/498/schedule/schedulings" rel="schedulings"><schedulings type="array">
<scheduling>
<id type="integer">1122</id>
<put-up type="datetime">2010-04-17T00:00:00Z</put-up>
<take-down type="datetime">2010-06-17T00:00:00Z</take-down>
<scheduling-type>archive</scheduling-type>
<link href="http://staging.schedule.bebanjo.net/api/title_groups/129" rel="title_group"/>
<link href="http://staging.schedule.bebanjo.net/api/titles/498" rel="title"/>
</scheduling>
</schedulings>
</link>
<link href="http://staging.schedule.bebanjo.net/api/titles/498" rel="title"/>
</schedule>

Of course, once you’ve got the URL of a resource, the next time you don’t need to navigate from the root of the API. You can (should!) start from the resource URL:

>> schedulings = Almodovar::Resource("http://staging.schedule.bebanjo.net/api/titles/498/schedule/schedulings", auth)
=> [<scheduling>
<id type="integer">1122</id>
<put-up type="datetime">2010-04-17T00:00:00Z</put-up>
<take-down type="datetime">2010-06-17T00:00:00Z</take-down>
<scheduling-type>archive</scheduling-type>
<link href="http://staging.schedule.bebanjo.net/api/title_groups/129" rel="title_group"/>
<link href="http://staging.schedule.bebanjo.net/api/titles/498" rel="title"/>
</scheduling>]

What if I want to access a specific node? Just do it:

>> schedulings.first.id
=> 112
>> schedulings.first.scheduling_type
=> "archive"

Note that fields with a hyphen are accessed with an underscore instead, otherwise ruby will think you are trying to substract (‘-’)

Next, explore the API docs to learn about other resources.

Creating resources¶ ↑

Resource collections have the create method. Just call it with the attributes you want your new resource to have!

>> jobs = Almodovar::Resource("http://sequence.example.com/api/work_areas/52/jobs", auth)
=> [<job> ... </job>, <job> ... </job>]
>> job = jobs.create(:job => {:name => "Wadus"})
=> <job> ... </job>
>> job.name
=> "Wadus"

Modifying resources¶ ↑

You can use the update method:

>> job = Almodovar::Resource("http://sequence.example.com/api/work_areas/52/jobs", auth).first
=> <job> ... </job>
>> job.update(:job => {:name => "Wadus wadus"})
=> ...
>> job.name
=> "Wadus wadus"

Updating associations¶ ↑

When updating a resource you can call the update method with other resources as parameters too. This allows you to create or update associations between resources (if they are supported, of course):

>> series = Almodovar::Resource("http://localhost:4001/api/title_groups/101", auth)
=> <title-group> ... </title-group>
>> title = Almodovar::Resource("http://localhost:4001/api/titles/1001", auth)
=> <title> ... </title>
>> title.update( title: { series: series } )

This will work the same with the create method, in case you need it.

Deleting resources¶ ↑

And exactly the same with the delete method:

>> job = Almodovar::Resource("http://sequence.example.com/api/work_areas/52/jobs", auth).first
=> <job> ... </job>
>> job.delete

Detailed error messages¶ ↑

In case an incorrect PUT/POST request fails with 422 response status, you can access list of errors using error_messages method of Almodovar::UnprocessableEntityError:

>> collection_entry = Almodovar::Resource("http://sequence.example.com/api/collection_entries/12345", auth)
=> <collection-entry> ... </collection-entry>
>> begin
    collection_entry.update(:collection_entry => {:position => 3.2})
   rescue Almodovar::UnprocessableEntityError => e
     e.error_messages
   end
=> ["Position must be an integer"]

To-do¶ ↑

Better error management
Write the conventions Almodovar expects in an API
Other authentication methods than digest

bebanjo/almodovar