BeBanjo Movida API documentation and Ruby client
Ruby
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
lib
spec
.gitignore
.rspec
.travis.yml
Gemfile
Gemfile.jruby
Gemfile.jruby.lock
Gemfile.lock
History.md
README.rdoc
Rakefile
almodovar.gemspec

README.rdoc

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"

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

Copyright © 2010 BeBanjo S.L., released under the MIT license