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).
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.
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"
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"
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.
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
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"]
-
Better error management
-
Write the conventions Almodovar expects in an API
-
Other authentication methods than digest
Copyright © 2023 BeBanjo S.L., released under the MIT license