restfully 0.7.1.rc5 → 0.7.1.rc6

data/LICENSE

@@ -1,5 +1,4 @@
-Copyright (c) 2009 Cyril Rohr
-Copyright (c) 2009 INRIA Rennes - Bretagne Atlantique
+Copyright (c) 2009-2011 Cyril Rohr, INRIA Rennes - Bretagne Atlantique
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -1,134 +1,78 @@
-# restfully
-
-An attempt at dynamically providing 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.
+# Restfully
+Restfully is a general-purpose client library for RESTful APIs. It is written in Ruby. Its goal is to abstract the nitty-gritty details of exchanging HTTP requests between the user-agent and the server. It also discovers resources at runtime, which means should the API change and add a new functionality, the client will automatically discover it.
+
+It works on simple concepts:
+
+1. All APIs are made of **resources**, and **collections of resources**.
+2. The **media-type** of a resource dictates the relationships between that resource and the other resources, and what it is possible to do with them.
+
+Therefore, Restfully can work with any reasonably RESTful API provided that:
+
+* The API returns semantically correct HTTP status codes;
+* The API make use of `GET`, `POST`, `PUT`, `DELETE` HTTP methods;
+* The API returns a valid `Content-Type` header in all responses;
+* The API returns a `Location` HTTP header on 201 and 202 responses;
+* The API returns links to other resources in all responses (the so-called HATEOAS constraint of REST).
+
+If one of the API `Content-Type` is not already supported by one of the `Restfully::MediaType` objects (see `lib/restfully/media_type`), then you just have to build it and register it with Restfully.
 
 ## Installation
 
     $ gem install restfully
 
+If you require media-types that need an XML parser, you must also install the `libxml-ruby` library:
+
+    $ gem install libxml-ruby
+
 ## Usage
 
 ### Command line
 
     $ export RUBYOPT="-rubygems"
-    $ restfully base_uri [-u username] [-p password]
+    $ restfully URI [-u username] [-p password]
   
-e.g., for the Grid5000 API:
+e.g., for the [Grid'5000 API](https://www.grid5000.fr/mediawiki/index.php/API):
 
     $ restfully https://api.grid5000.fr/sid/grid5000 -u username -p password
 
 If the connection was successful, you should get a prompt. You may enter:
 
-    irb(main):001:0> pp root
-
-to get back a pretty-printed output of the root resource:
-
-    #<Restfully::Resource:0x91f08c
-      @uri=#<URI::HTTP:0x123e30c URL:http://api.local/sid/grid5000>
-      LINKS
-        @environments=#<Restfully::Collection:0x917666>,
-        @sites=#<Restfully::Collection:0x9170d0>,
-        @version=#<Restfully::Resource:0x91852a>,
-        @versions=#<Restfully::Collection:0x917e68>
+    ruby-1.8.7-p249 > pp root
+    #<Resource:0x8108399c uri=https://api.grid5000.fr/sid/grid5000
+      RELATIONSHIPS
+        environments, self, sites, version, versions
       PROPERTIES
-        "uid"=>"grid5000",
-        "type"=>"grid",
-        "version"=>"4fe96b25d2cbfee16abe5a4fb999c82dbafc2ee8">
+        "uid"=>"grid5000"
+        "type"=>"grid"
+        "version"=>"da6abdd13e2e626f64502a648b784372eac790b1">
+     => nil
 
-You can see the `LINKS` and `PROPERTIES` headers that respectively indicate what links you can follow from there (by calling `root.link_name`) and what properties are available (by calling `root[property_name]`).
+And then follow the links advertised under the `RELATIONSHIPS` header to discover the other API resources. For instance, the `sites` resource can be accessed as follows:
 
-Let's say you want to access the collection of `sites`, you would enter:
-
-    irb(main):002:0> pp root.sites
-
-and get back:
-
-    #<Restfully::Collection:0x9170d0
-      @uri=#<URI::HTTP:0x122e128 URL:http://api.local/sid/grid5000/sites>
-      LINKS
-        @version=#<Restfully::Resource:0x8f553e>,
-        @versions=#<Restfully::Collection:0x8f52be>
-      PROPERTIES
-        "total"=>9,
-        "version"=>"4fe96b25d2cbfee16abe5a4fb999c82dbafc2ee8",
-        "offset"=>0
+    ruby-1.8.7-p249 > pp root.sites
+    #<Collection:0x8106d55c uri=https://api.grid5000.fr/sid/grid5000/sites
+      RELATIONSHIPS
+        self, version, versions
       ITEMS (0..9)/9
-        #<Restfully::Resource:0x9058bc uid="bordeaux">,
-        #<Restfully::Resource:0x903d0a uid="grenoble">,
-        #<Restfully::Resource:0x901cc6 uid="lille">,
-        #<Restfully::Resource:0x8fff0c uid="lyon">,
-        #<Restfully::Resource:0x8fe288 uid="nancy">,
-        #<Restfully::Resource:0x8fc4a6 uid="orsay">,
-        #<Restfully::Resource:0x8fa782 uid="rennes">,
-        #<Restfully::Resource:0x8f8bb2 uid="sophia">,
-        #<Restfully::Resource:0x8f6c9a uid="toulouse">>
-
-A Restfully::Collection is a special kind of Resource, which includes the Enumerable module, which means you can call all of its methods on the `Restfully::Collection` object. 
-For example:
-
-    irb(main):003:0> pp root.sites.find{|s| s['uid'] == 'rennes'}
-    #<Restfully::Resource:0x8fa782
-      @uri=#<URI::HTTP:0x11f4e64 URL:http://api.local/sid/grid5000/sites/rennes>
-      LINKS
-        @environments=#<Restfully::Collection:0x8f9ab2>,
-        @parent=#<Restfully::Resource:0x8f981e>,
-        @deployments=#<Restfully::Collection:0x8f935a>,
-        @clusters=#<Restfully::Collection:0x8f9d46>,
-        @version=#<Restfully::Resource:0x8fa354>,
-        @versions=#<Restfully::Collection:0x8fa0b6>,
-        @status=#<Restfully::Collection:0x8f95ee>
-      PROPERTIES
-        "name"=>"Rennes",
-        "latitude"=>48.1,
-        "location"=>"Rennes, France",
-        "security_contact"=>"rennes-staff@lists.grid5000.fr",
-        "uid"=>"rennes",
-        "type"=>"site",
-        "user_support_contact"=>"rennes-staff@lists.grid5000.fr",
-        "version"=>"4fe96b25d2cbfee16abe5a4fb999c82dbafc2ee8",
-        "description"=>"",
-        "longitude"=>-1.6667,
-        "compilation_server"=>false,
-        "email_contact"=>"rennes-staff@lists.grid5000.fr",
-        "web"=>"http://www.irisa.fr",
-        "sys_admin_contact"=>"rennes-staff@lists.grid5000.fr">
+        #<Resource:0x81055a9c uri=https://api.grid5000.fr/sid/grid5000/sites/bordeaux>
+        #<Resource:0x81040d54 uri=https://api.grid5000.fr/sid/grid5000/sites/grenoble>
+        #<Resource:0x8102c070 uri=https://api.grid5000.fr/sid/grid5000/sites/lille>
+        #<Resource:0x8101738c uri=https://api.grid5000.fr/sid/grid5000/sites/lyon>
+        #<Resource:0x81002658 uri=https://api.grid5000.fr/sid/grid5000/sites/nancy>
+        #<Resource:0x80fed924 uri=https://api.grid5000.fr/sid/grid5000/sites/orsay>
+        #<Resource:0x80fd8bb4 uri=https://api.grid5000.fr/sid/grid5000/sites/rennes>
+        #<Resource:0x80fc3dcc uri=https://api.grid5000.fr/sid/grid5000/sites/sophia>
+        #<Resource:0x80faf070 uri=https://api.grid5000.fr/sid/grid5000/sites/toulouse>>
+     => nil
 
-or:
+Note that we're using `pp` to pretty-print the output, but it's not required.
 
-    irb(main):006:0> root.sites.map{|s| s['uid']}.grep(/re/)
-    => ["grenoble", "rennes"]
+A Collection is a specific kind of Resource, and it has access to all the methods provided by the Ruby [Enumerable](http://www.rubydoc.info/stdlib/core/1.9.2/Enumerable) module.
 
-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"
-
-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:
+For ease of use and better security, you may prefer to use a configuration file to avoid re-entering the Restfully options every time:
 
     $ echo '
-    base_uri: https://api.grid5000.fr/sid/grid5000
+    uri: https://api.grid5000.fr/sid/grid5000
     username: MYLOGIN
     password: MYPASSWORD
     ' > ~/.restfully/api.grid5000.fr.yml && chmod 600 ~/.restfully/api.grid5000.fr.yml
@@ -140,12 +84,6 @@ 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:
-
-* `links` will return a hash whose keys are the name of the methods that can be called to navigate between resources;
-* `http_methods` will return an array containing the list of the HTTP methods that are allowed on the resource;
-
 ## Development
 
 ### Testing
@@ -163,4 +101,5 @@ A `Restfully::Resource` (and by extension its child `Restfully::Collection`) has
 
 ## Copyright
 
-Copyright (c) 2009 Cyril Rohr, INRIA Rennes - Bretagne Atlantique. See LICENSE for details.
+Copyright (c) 2009-2011 [Cyril Rohr](http://crohr.me), INRIA Rennes - Bretagne Atlantique. 
+See LICENSE for details.

data/lib/restfully/resource.rb

@@ -2,9 +2,9 @@ module Restfully
   # This class represents a Resource, which can be accessed and manipulated
   # via HTTP methods.
   #
-  # The <tt>#load</tt> method must have been called on the resource before
-  # trying to access its attributes or links.
-  #
+  # Some resources can be collection of other resources. 
+  # In that case the <tt>Restfully::Collection</tt> module is included in the <tt>Restfully::Resource</tt> class. 
+  # See the corresponding documentation for the list of additional methods that you can use on a collection resource.
   class Resource
     attr_reader :response, :request, :session
 
@@ -17,11 +17,10 @@ module Restfully
       @associations = {}
     end
 
-    # == Description
     # Returns the value corresponding to the specified key,
-    # among the list of resource properties
+    # among the list of resource properties.
     #
-    # == Usage
+    # e.g.:
     #   resource["uid"]
     #   => "rennes"
     def [](key)
@@ -31,26 +30,32 @@ module Restfully
       media_type.property(key)
     end
 
+    # Returns the resource URI.
     def uri
       request.uri
     end
 
+    # Returns the Restfully::MediaType object that was used to parse the response.
     def media_type
       response.media_type
     end
-    
+
+    # Does this resource contain only a fragment of the full resource?
     def complete?
       media_type.complete?
     end
 
+    # Is this resource a collection of items?
     def collection?
       media_type.collection?
     end
-    
+
+    # Returns the resource kind: "Collection" or "Resource".
     def kind
       collection? ? "Collection" : "Resource"
     end
-    
+
+    # Returns the "signature" of the resource. Used for (pretty-)inspection.
     def signature(closed=true)
       s = "#<#{kind}:0x#{object_id.to_s(16)}"
       s += " uri=#{uri.to_s}"
@@ -58,6 +63,9 @@ module Restfully
       s
     end
 
+    # Load the resource. The <tt>options</tt> Hash can contain any number of parameters among which:
+    # <tt>:head</tt>:: a Hash of HTTP headers to pass when fetching the resource.
+    # <tt>:query</tt>:: a Hash of query parameters to add to the URI when fetching the resource.
     def load(options = {})
       # Send a GET request only if given a different set of options
       if @request.update!(options) || @request.no_cache?
@@ -72,28 +80,29 @@ module Restfully
       
       build
     end
-    
+
+    # Returns the list of relationships for this resource, extracted from the resource links ("rel" attribute).
     def relationships
       response.links.map(&:id).sort
     end
-    
+
+    # Returns the Hash of properties for this resource.
     def properties
       media_type.property.reject{|k,v|        
         # do not return keys used for internal use
         k.to_s =~ HIDDEN_PROPERTIES_REGEXP
       }
     end
-    
-    # For the following methods, maybe it's better to always go through the
-    # cache instead of explicitly saying @request.no_cache! (and update the
-    # #load method accordingly)
-    
-    # Force reloading of the request
+
+    # Force reloading of the resource.
     def reload
       @request.no_cache!
       load
     end
 
+    # POST some payload on that resource URI.
+    # Either you pass a serialized payload as first argument, followed by an optional Hash of <tt>:head</tt> and <tt>:query</tt> parameters.
+    # Or you pass your payload as a Hash, and the serialization will occur based on the Content-Type you set (and only if a corresponding MediaType can be found in the MediaType catalog).
     def submit(*args)
       if allow?("POST")
         @request.no_cache!
@@ -104,6 +113,8 @@ module Restfully
       end
     end
 
+    # Send a DELETE HTTP request on the resource URI.
+    # See <tt>#load</tt> for the list of arguments this method can take.
     def delete(options = {})
       if allow?("DELETE")
         @request.no_cache!
@@ -113,6 +124,8 @@ module Restfully
       end
     end
 
+    # Send a PUT HTTP request with some payload on the resource URI.
+    # See <tt>#submit</tt> for the list of arguments this method can take.
     def update(*args)
       if allow?("PUT")
         @request.no_cache!
@@ -123,6 +136,7 @@ module Restfully
       end
     end
 
+    # Returns true if the resource supports the given HTTP <tt>method</tt> (String or Symbol).
     def allow?(method)
       response.allow?(method) || reload.response.allow?(method)
     end
@@ -173,8 +187,7 @@ module Restfully
       nil
     end
 
-    
-
+    # Build the resource after loading.
     def build
       metaclass = class << self; self; end
       # only build once
@@ -192,7 +205,8 @@ module Restfully
       # end
       self
     end
-    
+
+    # Reload itself if the resource is not <tt>#complete?</tt>.
     def expand
       reload unless complete?
       self

data/lib/restfully/session.rb

@@ -13,9 +13,34 @@ module Restfully
     attr_reader :config
     attr_writer :default_headers
 
+    # Builds a new client session.
+    # Takes a number of <tt>options</tt> as input.
+    # Yields or return the <tt>root</tt> Restfully::Resource object, and the Restfully::Session object.
+    #
+    # <tt>:configuration_file</tt>:: the location of a YAML configuration file that contains any of the parameters below.
+    # <tt>:uri</tt>:: the entry-point URI for this session.
+    # <tt>:logger</tt>:: a Logger object, used to display information.
+    # <tt>:require</tt>:: an Array of Restfully::MediaType objects to automatically require for this session.
+    # <tt>:retry_on_error</tt>:: the maximum number of attempts to make when a server (502,502,504) or connection error occurs.
+    # <tt>:wait_before_retry</tt>:: the number of seconds to wait before making another attempt when a server or connection error occurs.
+    # <tt>:default_headers</tt>:: a Hash of default HTTP headers to send with each request.
+    # <tt>:cache</tt>:: a Hash of parameters to configure the caching component. See <http://rtomayko.github.com/rack-cache/configuration> for more information.
+    # 
+    # e.g.
+    #   Restfully::Session.new(
+    #     :uri => "https://api.bonfire-project.eu:444/",
+    #     :username => "crohr",
+    #     :password => "PASSWORD",
+    #     :require => ['ApplicationVndBonfireXml']
+    #   ) {|root, session| p root}
+    #
     def initialize(options = {})
       @config = options.symbolize_keys
-      @logger = @config.delete(:logger) || Logger.new(STDERR)
+      @logger = @config.delete(:logger)
+      if @logger.nil?
+        @logger = Logger.new(STDERR)
+        @logger.level = Logger::INFO
+      end
 
       # Read configuration from file:
       config_file = @config.delete(:configuration_file) || ENV['RESTFULLY_CONFIG']
@@ -46,25 +71,30 @@ module Restfully
 
       disable RestClient::Rack::Compatibility
       authenticate(@config)
-      setup_cache
+      setup_cache((@config.delete(:cache) || {}).symbolize_keys)
 
       yield root, self if block_given?
     end
 
+    # Enable a RestClient Rack component.
     def enable(rack, *args)
       logger.info "Enabling #{rack.inspect}."
       RestClient.enable rack, *args
     end
 
+    # Disable a RestClient Rack component.
     def disable(rack, *args)
       logger.info "Disabling #{rack.inspect}."
       RestClient.disable rack, *args
     end
 
+    # Returns the list of middleware components enabled.
+    # See rest-client-components for more information.
     def middleware
       RestClient.components.map{|(rack, args)| rack}
     end
 
+    # Authnenticates the request using Basic Authentication.
     def authenticate(options = {})
       if options[:username]
         enable(
@@ -80,6 +110,7 @@ module Restfully
       Addressable::URI.join(uri.to_s, path.to_s)
     end
 
+    # Return the Hash of default HTTP headers that are sent with each request.
     def default_headers
       @default_headers ||= {
         'Accept' => '*/*',
@@ -87,6 +118,7 @@ module Restfully
       }
     end
 
+    # Returns the root Restfully::Resource.
     def root
       get(uri.path).load
     end
@@ -153,8 +185,9 @@ module Restfully
     end
 
     protected
-    def setup_cache
-      enable ::Rack::Cache, :verbose => (logger.level <= Logger::INFO)
+    def setup_cache(options = {})
+      opts = {:verbose => (logger.level <= Logger::INFO)}.merge(options)
+      enable ::Rack::Cache, opts
     end
 
     def error_message(request, response)

data/lib/restfully/version.rb

@@ -1,3 +1,3 @@
 module Restfully
-  VERSION = "0.7.1.rc5"
+  VERSION = "0.7.1.rc6"
 end

data/spec/restfully/session_spec.rb

@@ -11,17 +11,47 @@ describe Restfully::Session do
     }
   end
 
-  it "should initialize a session with the correct properties" do
-    session = Restfully::Session.new(@config.merge("key" => "value"))
-    session.logger.should == @logger
-    session.uri.should == Addressable::URI.parse(@uri)
-    session.config.should == {:wait_before_retry=>5, :key=>"value", :retry_on_error=>5}
-  end
+  describe "intialization" do
+    it "should initialize a session with the correct properties" do
+      session = Restfully::Session.new(@config.merge("key" => "value"))
+      session.logger.should == @logger
+      session.uri.should == Addressable::URI.parse(@uri)
+      session.config.should == {:wait_before_retry=>5, :key=>"value", :retry_on_error=>5}
+    end
 
-  it "should raise an error if no URI given" do
-    lambda{
-      Restfully::Session.new(@config.merge(:uri => ""))
-    }.should raise_error(ArgumentError)
+    it "should raise an error if no URI given" do
+      lambda{
+        Restfully::Session.new(@config.merge(:uri => ""))
+      }.should raise_error(ArgumentError)
+    end
+    
+    it "should add or replace additional headers to the default set" do
+      session = Restfully::Session.new(
+        @config.merge(:default_headers => {
+          'Accept' => 'application/xml',
+          'Cache-Control' => 'no-cache'
+        })
+      )
+      session.default_headers.should == {
+        'Accept' => 'application/xml',
+        'Cache-Control' => 'no-cache',
+        'Accept-Encoding' => 'gzip, deflate'
+      }
+    end
+    
+    it "should pass configuration options to Rack::Cache" do
+      session = Restfully::Session.new(@config.merge({
+        :cache => {
+          :metastore   => 'file:/var/cache/rack/meta',
+          :entitystore => 'file:/var/cache/rack/body'
+        }
+      }))
+      RestClient.components.should == [[Rack::Cache, [{
+        :verbose => true,
+        :metastore   => 'file:/var/cache/rack/meta',
+        :entitystore => 'file:/var/cache/rack/body'
+      }]]]
+    end
   end
 
   it "should fetch the root path [no URI path]" do
@@ -42,20 +72,6 @@ describe Restfully::Session do
     session.root.should == res
   end
 
-  it "should add or replace additional headers to the default set" do
-    session = Restfully::Session.new(
-      @config.merge(:default_headers => {
-        'Accept' => 'application/xml',
-        'Cache-Control' => 'no-cache'
-      })
-    )
-    session.default_headers.should == {
-      'Accept' => 'application/xml',
-      'Cache-Control' => 'no-cache',
-      'Accept-Encoding' => 'gzip, deflate'
-    }
-  end
-
   describe "middleware" do
     it "should only have Rack::Cache enabled by default" do
       session = Restfully::Session.new(@config)

metadata

@@ -1,15 +1,15 @@
 --- !ruby/object:Gem::Specification 
 name: restfully
 version: !ruby/object:Gem::Version 
-  hash: 15424103
+  hash: 15424097
   prerelease: 6
   segments: 
   - 0
   - 7
   - 1
   - rc
-  - 5
-  version: 0.7.1.rc5
+  - 6
+  version: 0.7.1.rc6
 platform: ruby
 authors: 
 - Cyril Rohr
@@ -17,7 +17,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-05-16 00:00:00 +02:00
+date: 2011-05-17 00:00:00 +02:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency