=Almodovar {<img src="http://travis-ci.org/bebanjo/almodovar.png" />}[http://travis-ci.org/bebanjo/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 http://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}[http://wiki.github.com/bebanjo/almodovar/] 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

Copyright (c) 2010 BeBanjo S.L., released under the MIT license