= restfully

An attempt at dynamically providing "clever" wrappers on top of RESTful APIs that follow the principle of Hyperlinks As The Engine Of Application State (HATEOAS). For it to work, the API must follow certain conventions (to be explained later).

Alpha work.

== Installation
  $ gem install restfully --source http://gemcutter.org

== Usage
=== Command line
  $ export RUBYOPT="-rubygems"
  $ restfully base_uri [root_path] [-u username] [-p password]
  
e.g., for the Grid5000 API:
  $ restfully https://api.grid5000.fr/sid /grid5000 -u username -p password

If the connection was successful, you should get a prompt. Call the +root+ function to see what are the available resources. <tt>@property</tt> means that you can call the +property+ method on the object. Other properties are available via the <tt>[]</tt> function.
e.g.:
  irb(main):005:0> root
  => #<Restfully::Resource:0x8848de
      	------------ META ------------
      	@uri: #<URI::Generic:0x11091a8 URL:/grid5000>
      	@uid: "grid5000"
      	@type: "grid"
      	@environments: Restfully::Collection
      	@sites: Restfully::Collection
      	@version: Restfully::Resource
      	@versions: Restfully::Collection
      	------------ PROPERTIES ------------
      	"version" => "4fe96b25d2cbfee16abe5a4fb999c82dbafc2ee8">
    
   irb(main):006:0> root.uri
   => #<URI::Generic:0x11091a8 URL:/grid5000>
   
   irb(main):007:0> root.sites
   => #<Restfully::Collection:0x881f6c
       	------------ META ------------
       	@uri: "/grid5000/sites"
       	@offset: 0
       	@total: 9
       	@version: Restfully::Resource
       	@versions: Restfully::Collection
       	------------ PROPERTIES ------------
       	"version" => "4fe96b25d2cbfee16abe5a4fb999c82dbafc2ee8"
       	------------ ITEMS ------------
       	Restfully::Resource
       	Restfully::Resource
       	Restfully::Resource
       	Restfully::Resource
       	Restfully::Resource
       	Restfully::Resource
       	Restfully::Resource
       	Restfully::Resource
       	Restfully::Resource>
   
   irb(main):008:0> root.sites.by_uid('rennes').clusters.by_uid('paradent').nodes.by_uid('paradent-1').metrics.by_uid('mem_free', 'cpu_idle', 'bytes_in')
   => [#<Restfully::Resource:0x4259a
       	------------ META ------------
       	@uri: "/grid5000/sites/rennes/clusters/paradent/nodes/paradent-1/metrics/mem_free"
       	@uid: "mem_free"
       	@type: "metric"
       	@parent: Restfully::Resource
       	@timeseries: Restfully::Resource
       	------------ PROPERTIES ------------
       	"last_update" => -901639018
       	"step" => 15
       	"timeseries" => [{"xff"=>0.5, "cf"=>"AVERAGE", "rows"=>244, "pdp_per_row"=>1}, {"xff"=>0.5, "cf"=>"AVERAGE", "rows"=>244, "pdp_per_row"=>24}, {"xff"=>0.5, "cf"=>"AVERAGE", "rows"=>244, "pdp_per_row"=>168}, {"xff"=>0.5, "cf"=>"AVERAGE", "rows"=>244, "pdp_per_row"=>672}, {"xff"=>0.5, "cf"=>"AVERAGE", "rows"=>374, "pdp_per_row"=>5760}]>, #<Restfully::Resource:0x12444
       	------------ META ------------
       	@uri: "/grid5000/sites/rennes/clusters/paradent/nodes/paradent-1/metrics/cpu_idle"
       	@uid: "cpu_idle"
       	@type: "metric"
       	@parent: Restfully::Resource
       	@timeseries: Restfully::Resource
       	------------ PROPERTIES ------------
       	"last_update" => -901639018
       	"step" => 15
       	"timeseries" => [{"xff"=>0.5, "cf"=>"AVERAGE", "rows"=>244, "pdp_per_row"=>1}, {"xff"=>0.5, "cf"=>"AVERAGE", "rows"=>244, "pdp_per_row"=>24}, {"xff"=>0.5, "cf"=>"AVERAGE", "rows"=>244, "pdp_per_row"=>168}, {"xff"=>0.5, "cf"=>"AVERAGE", "rows"=>244, "pdp_per_row"=>672}, {"xff"=>0.5, "cf"=>"AVERAGE", "rows"=>374, "pdp_per_row"=>5760}]>, #<Restfully::Resource:0xe4c870
       	------------ META ------------
       	@uri: "/grid5000/sites/rennes/clusters/paradent/nodes/paradent-1/metrics/bytes_in"
       	@uid: "bytes_in"
       	@type: "metric"
       	@parent: Restfully::Resource
       	@timeseries: Restfully::Resource
       	------------ PROPERTIES ------------
       	"last_update" => -901639018
       	"step" => 15
       	"timeseries" => [{"xff"=>0.5, "cf"=>"AVERAGE", "rows"=>244, "pdp_per_row"=>1}, {"xff"=>0.5, "cf"=>"AVERAGE", "rows"=>244, "pdp_per_row"=>24}, {"xff"=>0.5, "cf"=>"AVERAGE", "rows"=>244, "pdp_per_row"=>168}, {"xff"=>0.5, "cf"=>"AVERAGE", "rows"=>244, "pdp_per_row"=>672}, {"xff"=>0.5, "cf"=>"AVERAGE", "rows"=>374, "pdp_per_row"=>5760}]>]
   
   irb(main):009:0> root.version
   => #<Restfully::Resource:0x8facf0
        ------------ META ------------
        @uri: "/grid5000/versions/ee1f8111c8835496a9e4a6f7c9491c0238ee9827"
        @uid: "ee1f8111c8835496a9e4a6f7c9491c0238ee9827"
        @type: "version"
        @parent: Restfully::Resource
        ------------ PROPERTIES ------------
        "author" => "Cyril Constantin <>"
        "date" => "Fri, 11 Sep 2009 14:32:48 GMT"
        "message" => "[environments] update of environments on sites">

You may also prefer to use a configuration file to avoid entering the command line options:
  $ echo '
  base_uri: https://api.grid5000.fr/sid
  root_path: /grid5000
  username: MYLOGIN
  password: MYPASSWORD
  ' > ~/somewhere/api.grid5000.fr.yml

And then:
  $ restfully -c ~/somewhere/api.grid5000.fr.yml

=== As a library
See the +examples+ directory for examples.

== Note on Patches/Pull Requests
 
* Fork the project.
* Make your feature addition or bug fix.
* Add tests for it. This is important so I don't break it in a future version unintentionally.
* Commit, do not mess with rakefile, version, or history (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull).
* Send me a pull request. Bonus points for topic branches.

== Testing

* rake spec, or
* run autotest in the project directory.

== Copyright

Copyright (c) 2009 Cyril Rohr, INRIA Rennes - Bretagne Atlantique. See LICENSE for details.