restfully 0.4.1 → 0.5.0

data/CHANGELOG

@@ -1,6 +1,6 @@
 0.4.1
 * added a require 'yaml' in restfully.rb (priteau);
-* added an introductory message when suing the command-line tool;
+* added an introductory message when using the command-line tool;
 * removed [root_path] from the list of options in command-line client 'Usage' banner (priteau);
 * added test for :configuration_file option;
 * tests are no longer failing on ruby1.9;

data/README.rdoc

@@ -1,8 +1,25 @@
 = 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.
+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). It does not require to use specific (and often complex) server-side libraries, but a few constraints and conventions must be followed:
+1. Return sensible HTTP status codes;
+2. Make use of GET, POST, PUT, DELETE HTTP methods;
+3. Return a Location HTTP header in 201 or 202 responses;
+4. Return a <tt>links</tt> property in all responses to a GET request, that contains a list of link objects:
+   
+    {
+      "property": "value",
+      "links": [
+        {"rel": "self", "href": "uri/to/resource", "type": "application/vnd.whatever+json;level=1,application/json"},
+        {"rel": "parent", "href": "uri/to/parent/resource", "type": "application/json"} 
+        {"rel": "collection", "href": "uri/to/collection", "title": "my_collection", "type": "application/json"}, 
+        {"rel": "member", "href": "uri/to/member", "title": "member_title", "type": "application/json"}
+      ]
+    }
+   
+   * Adding a <tt>parent</tt> link automatically creates a <tt>#parent</tt> method on the current resource. 
+   * Adding a <tt>collection</tt> link automatically creates a <tt>#my_collection</tt> method that will fetch the Collection when called. 
+   * Adding a <tt>member</tt> link automatically creates a <tt>#member_title</tt> method that will fetch the Resource when called.
+5. Advertise allowed HTTP methods in the response to GET requests by returning a <tt>Allow</tt> HTTP header containing a comma-separated list of the HTTP methods that can be used on the resource. This will allow the automatic generation of methods to interact with the resource. e.g.: advertising a <tt>POST</tt> method (<tt>Allow: GET, POST</tt>) will result in the creation of a <tt>submit</tt> method on the resource.
 
 == Installation
   $ gem install restfully --source http://gemcutter.org
@@ -89,8 +106,11 @@ or:
   irb(main):006:0> root.sites.map{|s| s['uid']}.grep(/re/)
   => ["grenoble", "rennes"]
 
+A shortcut is available to find a specific entry in a collection, by entering the searched uid as a Symbol:
+  irb(main):007:0> root.sites[:rennes]
+  # will find the item whose uid is "rennes"
 
-To enter the command-line options, you may prefer to use a configuration file to avoid re-entering the options every time you use the client:
+For ease of use and better security, you may prefer to use a configuration file to avoid re-entering the options every time you use the client:
   $ echo '
   base_uri: https://api.grid5000.fr/sid/grid5000
   username: MYLOGIN
@@ -103,6 +123,11 @@ And then:
 === As a library
 See the +examples+ directory for examples.
 
+== Discovering the API capabilities
+A Restfully::Resource (and by extension its child Restfully::Collection) has the following methods available for introspection:
+* <tt>links</tt> will return a hash whose keys are the name of the methods that can be called to navigate between resources;
+* <tt>http_methods</tt> will return an array containing the list of the HTTP methods that are allowed on the resource;
+
 == Note on Patches/Pull Requests
  
 * Fork the project.

data/VERSION

@@ -1 +1 @@
-0.4.1
+0.5.0

data/examples/grid5000.rb

@@ -7,10 +7,15 @@ require File.dirname(__FILE__)+'/../lib/restfully'
 logger = Logger.new(STDOUT)
 logger.level = Logger::WARN
 
-# Restfully.adapter = Restfully::HTTP::RestClientAdapter
-# Restfully.adapter = Patron::Session
 RestClient.log = 'stdout'
-Restfully::Session.new(:base_uri => 'http://api.local/sid/grid5000', :logger => logger) do |grid, session|
+
+# This yaml file contains the following attributes:
+# username: my_username
+# password: my_password
+options = YAML.load_file(File.expand_path('~/.restfully/api.grid5000.fr.yml')) 
+options[:base_uri] = 'https://api.grid5000.fr/sid/grid5000'
+options[:logger] = logger
+Restfully::Session.new(options) do |grid, session|
   grid_stats = {'hardware' => {}, 'system' => {}}
   grid.sites.each do |site|
     site_stats = site.status.inject({'hardware' => {}, 'system' => {}}) {|accu, node_status|

data/lib/restfully/collection.rb

@@ -28,6 +28,16 @@ module Restfully
     def each(*args, &block)
       @items.each(*args, &block)
     end
+    
+    # if property is a Symbol, it tries to find the corresponding item whose uid.to_sym is matching the property
+    # else, returns the result of calling <tt>[]</tt> on its superclass.
+    def [](property)
+      if property.kind_of?(Symbol)
+        find{|i| i['uid'] == property.to_s}
+      else
+        super(property)
+      end
+    end
 
     def populate_object(key, value)
       case key
@@ -38,7 +48,7 @@ module Restfully
           self_link = (item['links'] || []).
             map{|link| Link.new(link)}.detect{|link| link.self?}
           if self_link && self_link.valid?
-            @items.push Resource.new(uri.merge(self_link.href), session).load(:body => item)
+            @items.push Resource.new(uri_for(self_link.href), session).load(:body => item)
           else
             session.logger.warn "Resource #{key} does not have a 'self' link. skipped."
           end

data/lib/restfully/resource.rb

@@ -37,6 +37,7 @@ module Restfully
       @executed_requests = Hash.new
       @links = Hash.new
       @properties = Hash.new
+      @status = :stale
       self
     end
     
@@ -65,33 +66,84 @@ module Restfully
     # properties and links
     # <tt>options</tt>:: list of options to pass to the request (see below)
     # == Options
-    # <tt>:reload</tt>:: if set to true, a GET request will be triggered even if the resource has already been loaded [default=false]
-    # <tt>:query</tt>:: a hash of query parameters to pass along the request. E.g. : resource.load(:query => {:from => (Time.now-3600).to_i, :to => Time.now.to_i})
-    # <tt>:headers</tt>:: a hash of HTTP headers to pass along the request. E.g. : resource.load(:headers => {'Accept' => 'application/json'})
-    # <tt>:body</tt>:: if you already have the unserialized response body of this resource, you may pass it so that the GET request is not triggered.
+    # <tt>:reload</tt>:: if set to true, a GET request will be triggered 
+    #                    even if the resource has already been loaded [default=false]
+    # <tt>:query</tt>:: a hash of query parameters to pass along the request. 
+    #                   E.g. : resource.load(:query => {:from => (Time.now-3600).to_i, :to => Time.now.to_i})
+    # <tt>:headers</tt>:: a hash of HTTP headers to pass along the request. 
+    #                     E.g. : resource.load(:headers => {'Accept' => 'application/json'})
+    # <tt>:body</tt>:: if you already have the unserialized response body of this resource, 
+    #                  you may pass it so that the GET request is not triggered.
     def load(options = {})
       options = options.symbolize_keys
-      force_reload = !!options.delete(:reload)
+      force_reload = !!options.delete(:reload) || stale?
       if !force_reload && (request = executed_requests['GET']) && request['options'] == options && request['body']
         self
       else  
         reset
+        if options[:body]
+          body = options[:body]
+          headers = nil
+        else
+          response = session.get(uri, options)
+          body = response.body
+          headers = response.headers
+        end
         executed_requests['GET'] = {
           'options' => options, 
-          'body' => options[:body] || session.get(uri, options).body
+          'body' =>  body,
+          'headers' => headers
         }
         executed_requests['GET']['body'].each do |key, value|
           populate_object(key, value)
         end
+        @status = :loaded
         self
       end
     end
   
+    # == Description
+    # Executes a POST request on the resource, reload it and returns self if successful.
+    # If the response status is different than 2xx, raises a HTTP::ClientError or HTTP::ServerError.
+    # <tt>payload</tt>:: the input body of the request.
+    #                    It may be a serialized string, or a ruby object 
+    #                    (that will be serialized according to the given or default content-type).
+    # <tt>options</tt>:: list of options to pass to the request (see below)
+    # == Options
+    # <tt>:query</tt>:: a hash of query parameters to pass along the request. 
+    #                   E.g. : resource.submit("body", :query => {:param1 => "value1"})
+    # <tt>:headers</tt>:: a hash of HTTP headers to pass along the request. 
+    #                     E.g. : resource.submit("body", :headers => {:accept => 'application/json', :content_type => 'application/json'})
     def submit(payload, options = {})
       options = options.symbolize_keys
       raise NotImplementedError, "The POST method is not allowed for this resource." unless http_methods.include?('POST')
-      raise ArgumentError, "You must pass a payload string" unless payload.kind_of?(String)
-      session.post(payload, options)
+      raise ArgumentError, "You must pass a payload" if payload.nil?
+      headers = {
+        :content_type => (executed_requests['GET']['headers']['Content-Type'] || "application/x-www-form-urlencoded").split(/,/).sort{|a,b| a.length <=> b.length}[0],
+        :accept => (executed_requests['GET']['headers']['Content-Type'] || "text/plain")
+      }.merge(options[:headers] || {})
+      options = {:headers => headers}
+      options.merge!(:query => options[:query]) unless options[:query].nil?
+      response = session.post(self.uri, payload, options) # raises an exception if there is an error
+      stale!
+      if [201, 202].include?(response.status)
+        Resource.new(uri_for(response.headers['Location']), session).load
+      else
+        reload
+      end
+    end
+    
+    
+    def stale!; @status = :stale;  end
+    def stale?; @status == :stale; end
+    
+    def uri_for(path)
+      uri.merge(URI.parse(path.to_s))
+    end
+    
+    def reload
+      current_options = executed_requests['GET']['options'] rescue {}
+      self.load(current_options.merge(:reload => true))
     end
     
     # == Description
@@ -101,11 +153,8 @@ module Restfully
     #   => ['GET', 'POST']
     # 
     def http_methods
-      if executed_requests['HEAD'].nil?
-        response = session.head(uri)
-        executed_requests['HEAD'] = {'headers' => response.headers}
-      end
-      (executed_requests['HEAD']['headers']['Allow'] || "GET").split(/,\s*/)
+      reload if executed_requests['GET'].nil? || executed_requests['GET']['headers'].nil?
+      (executed_requests['GET']['headers']['Allow'] || "GET").split(/,\s*/)
     end
     
     def respond_to?(method, *args)
@@ -118,6 +167,7 @@ module Restfully
     
     def pretty_print(pp)
       pp.text "#<#{self.class}:0x#{self.object_id.to_s(16)}"
+      pp.text " uid=#{self['uid'].inspect}" if self.class == Resource
       pp.nest 2 do
         pp.breakable
         pp.text "@uri="

data/lib/restfully.rb

@@ -14,7 +14,7 @@ require 'restfully/collection'
 
 
 module Restfully
-  VERSION = "0.4.1"
+  VERSION = "0.5.0"
   class << self
     attr_accessor :adapter
   end

data/restfully.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{restfully}
-  s.version = "0.4.1"
+  s.version = "0.5.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Cyril Rohr"]
-  s.date = %q{2009-11-16}
+  s.date = %q{2009-12-08}
   s.default_executable = %q{restfully}
   s.description = %q{Experimental code for auto-generation of wrappers on top of RESTful APIs that follow HATEOAS principles and provide OPTIONS methods and/or Allow headers.}
   s.email = %q{cyril.rohr@gmail.com}

data/spec/collection_spec.rb

@@ -20,79 +20,70 @@ describe Collection do
     it "should have a :offset attribute" do
       @collection["offset"].should == 0
     end
+    
+    it "should try to find the matching item in the collection when calling [] with a symbol" do
+      rennes = @collection[:rennes]
+      rennes.class.should == Restfully::Resource
+      rennes['uid'].should == 'rennes'
+    end
   end  
   
-  describe "loading" do
-    before(:all) do
-      @uri = URI.parse('http://api.local/x/y/z')
-      @raw = fixture("grid5000-sites.json")
-      @response_200 = Restfully::HTTP::Response.new(200, {'Content-Type' => 'application/json;charset=utf-8', 'Content-Length' => @raw.length}, @raw)
-      @logger = Logger.new(STDOUT)
-    end
-    it "should not load if already loaded and no :reload" do
-      collection = Collection.new(@uri, mock("session"))
-      options = {:headers => {'key' => 'value'}}
-      collection.should_receive(:executed_requests).and_return({'GET' => {'options' => options, 'body' => {"key" => "value"}}})
-      collection.load(options.merge(:reload => false)).should == collection
-    end
-    it "should load when :reload param is true [already loaded]" do
-      collection = Collection.new(@uri, session=mock("session", :logger => Logger.new(STDOUT)))
-      session.should_receive(:get).and_return(@response_200)
-      collection.load(:reload => true).should == collection    
+  describe "populating collection" do
+    before do
+      @uri = "http://server.com/path/to/collection"
+      @session = mock("session", :logger => Logger.new($stderr))
+      @collection = Collection.new(@uri, @session)
     end
-    it "should load when force_reload is true [not loaded]" do
-      collection = Collection.new(@uri, session=mock("session", :logger => Logger.new(STDOUT)))
-      session.should_receive(:get).and_return(@response_200)
-      collection.load(:reload => true).should == collection    
+    it "should define links" do
+      Link.should_receive(:new).with({"rel" => "self", "href" => "/path/to/collection"}).and_return(link1=mock("link1"))
+      Link.should_receive(:new).with({"rel" => "member", "href" => "/path/to/member", "title" => "member_title"}).and_return(link2=mock("link2"))
+      @collection.should_receive(:define_link).with(link1)
+      @collection.should_receive(:define_link).with(link2)
+      @collection.populate_object("links", [
+        {"rel" => "self", "href" => "/path/to/collection"},
+        {"rel" => "member", "href" => "/path/to/member", "title" => "member_title"}
+      ])
     end
-    it "should force reload when query parameters are given" do
-      collection = Collection.new(@uri, session=mock("session", :logger => Logger.new(STDOUT)))
-      session.should_receive(:get).and_return(@response_200)
-      collection.load(:query => {:q1 => 'v1'}).should == collection
+    it "should create a new resource for each item" do
+      items = [
+        {
+          'links' => [
+            {'rel' => 'self', 'href' => '/grid5000/sites/rennes'},
+            {'rel' => 'collection', 'href' => '/grid5000/sites/rennes/versions', 'title' => 'versions'}
+          ],
+          'uid' => 'rennes'
+        }
+      ]
+      @collection.populate_object("items", items)
+      @collection.find{|i| i['uid'] == 'rennes'}.class.should == Restfully::Resource
     end
+
     it "should not initialize resources lacking a self link" do
-      collection = Collection.new(@uri, session = mock("session", :get => mock("restfully response", :body => {
-        "total" => 1,
-        "offset" => 0,
-        "items" => [
-          {
-            'links' => [
-              {'rel' => 'collection', 'href' => '/grid5000/sites/rennes/versions', 'resolvable' => false, 'title' => 'versions'}
-            ],
-            'uid' => 'rennes'
-          }
-        ]
-      }), :logger => @logger))
-      Resource.should_not_receive(:new)
-      collection.load
-      collection.find{|i| i['uid'] == 'rennes'}.should be_nil
+      items = [
+        {
+          'links' => [
+            {'rel' => 'collection', 'href' => '/grid5000/sites/rennes/versions', 'resolvable' => false, 'title' => 'versions'}
+          ],
+          'uid' => 'rennes'
+        }
+      ]
+      @collection.populate_object("items", items)
+      @collection.items.should be_empty
     end
-    it "should initialize resources having a self link" do
-      collection = Collection.new(@uri, session = mock("session", :get => mock("restfully response", :body => {
-        "total" => 1,
-        "offset" => 0,
-        "items" => [
-          {
-            'links' => [
-              {'rel' => 'self', 'href' => '/grid5000/sites/rennes'},
-              {'rel' => 'collection', 'href' => '/grid5000/sites/rennes/versions', 'title' => 'versions'}
-            ],
-            'uid' => 'rennes'
-          }
-        ]
-      }), :logger => @logger))
-      collection.load
-      collection.length.should == 1
-      collection.find{|i| i['uid'] == 'rennes'}.class.should == Restfully::Resource
+    it "should store its properties in the internal hash" do
+      @collection.populate_object("uid", "rennes")
+      @collection.populate_object("list_of_values", [1,2,"whatever", {:x => :y}])
+      @collection.populate_object("hash", {"a" => [1,2], "b" => "c"})
+      @collection.properties.should == {
+        "hash"=>{"a"=>[1, 2], "b"=>"c"}, 
+        "list_of_values"=>[1, 2, "whatever", {:x=>:y}], 
+        "uid"=>"rennes"
+      }
+      @collection["uid"].should == "rennes"
+      @collection["hash"].should == {"a"=>[1, 2], "b"=>"c"}
+      @collection["list_of_values"].should == [1, 2, "whatever", {:x=>:y}]
     end
-    it "should correctly initialize its resources [integration test]" do
-      collection = Collection.new(@uri, session=mock("session", :logger => Logger.new(STDOUT), :get => @response_200))
-      collection.load
-      collection.uri.should == @uri
-      collection.find{|i| i['uid'] == 'rennes'}["uid"].should == 'rennes'
-      collection.find{|i| i['uid'] == 'rennes'}["type"].should == 'site'
-      collection.map{|s| s['uid']}.should =~ ['rennes', 'lille', 'bordeaux', 'nancy', 'sophia', 'toulouse', 'lyon', 'grenoble', 'orsay']
-    end 
   end
+
   
 end

data/spec/resource_spec.rb

@@ -5,6 +5,7 @@ include Restfully
 describe Resource do
   before do
     @logger = Logger.new(STDOUT)
+    @uri = URI.parse("http://api.local/x/y/z")
   end
   
   describe "accessors" do
@@ -67,7 +68,6 @@ describe Resource do
         }
       }
       @response_200 = Restfully::HTTP::Response.new(200, {'Content-Type' => 'application/json;utf-8', 'Content-Length' => @raw.length}, @raw.to_json)
-      @uri = URI.parse("http://api.local/x/y/z")
     end
     it "should not be loaded in its initial state" do
       resource = Resource.new(@uri, mock('session'))
@@ -110,7 +110,7 @@ describe Resource do
           {'rel' => 'collection', 'href' => '/grid5000/sites/rennes/versions', 'resolvable' => false, 'title' => 'versions'}
         ],
         'uid' => 'rennes'
-      }), :logger => @logger))
+      }, :headers => {}), :logger => @logger))
       Collection.should_receive(:new).with(@uri.merge('/grid5000/sites/rennes/versions'), session, :title => 'versions').and_return(collection=mock("restfully collection"))
       resource.load
       resource.links['versions'].should == collection
@@ -121,7 +121,7 @@ describe Resource do
           {'rel' => 'self', 'href' => '/grid5000/sites/rennes'}
         ],
         'uid' => 'rennes'
-      }), :logger => @logger))
+      }, :headers => {}), :logger => @logger))
       resource.uri.should == @uri
       resource.load
       resource.uri.should == @uri
@@ -132,7 +132,7 @@ describe Resource do
           {'rel' => 'member', 'href' => '/grid5000/sites/rennes/versions/123', 'title' => 'version'}
         ],
         'uid' => 'rennes'
-      }), :logger => @logger))
+      }, :headers => {}), :logger => @logger))
       Resource.should_receive(:new).with(@uri.merge('/grid5000/sites/rennes/versions/123'), session, :title => 'version').and_return(member=mock("restfully resource"))
       resource.load
       resource.links['version'].should == member
@@ -144,7 +144,7 @@ describe Resource do
           {'rel' => 'parent', 'href' => '/grid5000'}
         ],
         'uid' => 'rennes'
-      }), :logger => @logger))
+      }, :headers => {}), :logger => @logger))
       Resource.should_receive(:new).with(@uri.merge('/grid5000'), session).and_return(parent=mock("restfully resource"))
       resource.load
       resource.links['parent'].should == parent
@@ -157,7 +157,7 @@ describe Resource do
           {'rel' => 'collection', 'href' => '/has/no/title'} 
         ],
         'uid' => 'rennes'
-      }), :logger => @logger))
+      }, :headers => {}), :logger => @logger))
       resource.load
       resource.links.should be_empty
     end
@@ -170,4 +170,62 @@ describe Resource do
       resource.links.keys.should =~ ['versions', 'clusters', 'environments', 'status', 'parent', 'version']
     end
   end
+  
+  
+  describe "submitting" do
+    before do
+      @resource = Resource.new(@uri, @session = mock("session", :logger => @logger))
+      @resource.stub!(:http_methods).and_return(['GET', 'POST'])
+      @resource.stub!(:executed_requests).and_return({
+        'GET' => {'headers' => {'Content-Type' => 'application/vnd.fr.grid5000.api.Job+json;level=1,application/json'}, 'options' => {:query => {:q1 => 'v1'}}}
+      })
+    end
+    describe "setting input body and options" do
+      before do
+        @resource.stub!(:reload).and_return(@resource)
+        @response = mock("http response", :status => 200)
+      end
+      it "should raise a NotImplementedError if the resource does not allow POST" do
+        @resource.should_receive(:http_methods).and_return(['GET'])
+        lambda{@resource.submit("whatever")}.should raise_error(NotImplementedError, /POST method is not allowed for this resource/)
+      end
+      it "should raise an error if the input body is nil" do
+        lambda{@resource.submit(nil)}.should raise_error(ArgumentError, /You must pass a payload/)
+      end
+      it "should pass the body as-is if the given body is a string" do
+        @session.should_receive(:post).with(@resource.uri, "whatever", :headers => {
+          :accept => 'application/vnd.fr.grid5000.api.Job+json;level=1,application/json', 
+          :content_type => 'application/json'}
+          ).and_return(@response)
+        @resource.submit("whatever")
+      end
+      it "should also pass the body as-is if the given body is an object" do
+        body = {:key => 'value'}
+        @session.should_receive(:post).with(@resource.uri, body, :headers => {
+          :accept => 'application/vnd.fr.grid5000.api.Job+json;level=1,application/json', 
+          :content_type => 'application/json'}).and_return(@response)
+        @resource.submit(body)
+      end
+      it "should set the Content-Type header to the specified mime-type if given" do
+        @session.should_receive(:post).with(@resource.uri, "whatever", :headers => {
+          :accept => 'application/vnd.fr.grid5000.api.Job+json;level=1,application/json', 
+          :content_type => 'application/xml'}).and_return(@response)
+        @resource.submit("whatever", :headers => {:content_type => 'application/xml'})
+      end
+    end
+    [201, 202].each do |status|
+      it "should return the resource referenced in the Location header after a successful submit (status=#{status})" do
+        @session.should_receive(:post).and_return(response = mock("http response", :status => status, :headers => {'Location' => '/path/to/new/resource'}))
+        @resource.should_receive(:uri_for).with('/path/to/new/resource').and_return(new_resource_uri = mock("uri"))
+        Resource.should_receive(:new).with(new_resource_uri, @session).and_return(new_resource = mock("resource"))
+        new_resource.should_receive(:load).and_return(new_resource)
+        @resource.submit("whatever").should == new_resource
+      end
+    end
+    it "should reload the resource if the response status is 2xx (and not 201 or 202)" do
+      @session.should_receive(:post).and_return(response = mock("http response", :status => 200, :headers => {'Location' => '/path/to/new/resource'}))
+      @resource.should_receive(:reload).and_return(@resource)
+      @resource.submit("whatever").should == @resource
+    end
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: restfully
 version: !ruby/object:Gem::Version 
-  version: 0.4.1
+  version: 0.5.0
 platform: ruby
 authors: 
 - Cyril Rohr
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-11-16 00:00:00 +01:00
+date: 2009-12-08 00:00:00 +01:00
 default_executable: restfully
 dependencies: 
 - !ruby/object:Gem::Dependency