Project

almodovar

0.02
A long-lived project that still receives updates
BeBanjo API client
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
 Dependencies

Runtime

>= 2.3.6
>= 0
>= 0
>= 1.12.0
>= 3.2.5
 Project Readme

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

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