restfully 0.6.3 → 0.7.0.pre

data/README.md

@@ -0,0 +1,166 @@
+# 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.
+
+## Installation
+
+    $ gem install restfully
+
+## Usage
+
+### Command line
+
+    $ export RUBYOPT="-rubygems"
+    $ restfully base_uri [-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. 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>
+      PROPERTIES
+        "uid"=>"grid5000",
+        "type"=>"grid",
+        "version"=>"4fe96b25d2cbfee16abe5a4fb999c82dbafc2ee8">
+
+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]`).
+
+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
+      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">
+
+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"
+
+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
+    password: MYPASSWORD
+    ' > ~/.restfully/api.grid5000.fr.yml && chmod 600 ~/.restfully/api.grid5000.fr.yml
+
+And then:
+
+    $ restfully -c ~/.restfully/api.grid5000.fr.yml
+
+### 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
+
+* `rake spec`; or
+* run `autotest` in the project directory.
+
+### 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. 
+
+## Copyright
+
+Copyright (c) 2009 Cyril Rohr, INRIA Rennes - Bretagne Atlantique. See LICENSE for details.

data/Rakefile

@@ -1,47 +1,47 @@
 require 'rubygems'
 require 'rake'
+require 'rspec/core/rake_task'
 
-begin
-  require 'jeweler'
-  Jeweler::Tasks.new do |gem|
-    gem.name = "restfully"
-    gem.summary = %Q{Experimental code for auto-generation of wrappers on top of RESTful APIs that follow some specific conventions.}
-    gem.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.}
-    gem.email = "cyril.rohr@gmail.com"
-    gem.homepage = "http://github.com/crohr/restfully"
-    gem.authors = ["Cyril Rohr"]
-    gem.add_dependency "rest-client", '>= 1.4'
-    gem.add_dependency "json", '>= 1.2.0'
-    gem.add_dependency "backports"
-    gem.add_development_dependency "webmock"
-    gem.add_development_dependency "rspec"
-    gem.add_development_dependency "json"
-    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
-  end
+ROOT_DIR = File.dirname(__FILE__)
 
-rescue LoadError
-  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = 'restfully'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
 end
 
-require 'spec/rake/spectask'
-Spec::Rake::SpecTask.new(:spec) do |spec|
-  spec.libs << 'lib' << 'spec'
-  spec.spec_files = FileList['spec/**/*_spec.rb']
+desc "Run Tests"
+RSpec::Core::RakeTask.new(:spec) do |t|
+  t.rcov = false
+  t.pattern = 'spec/**/*_spec.rb'
 end
 
-Spec::Rake::SpecTask.new(:rcov) do |spec|
-  spec.libs << 'lib' << 'spec'
-  spec.pattern = 'spec/**/*_spec.rb'
-  spec.rcov = true
+desc "Run Test coverage"
+RSpec::Core::RakeTask.new(:rcov) do |t|
+  t.rcov = true
+  t.pattern = 'spec/**/*_spec.rb'
+  t.rcov_opts = ['-Ispec', '--exclude', 'spec']
 end
 
 task :default => :spec
 
-require 'rake/rdoctask'
-Rake::RDocTask.new do |rdoc|
-  rdoc.rdoc_dir = 'rdoc'
-  rdoc.title = 'restfully'
-  rdoc.options << '--line-numbers' << '--inline-source'
-  rdoc.rdoc_files.include('README*')
-  rdoc.rdoc_files.include('lib/**/*.rb')
-end
+task :clean do
+  Dir.chdir(ROOT_DIR) do
+    rm_f "*.gem"
+  end
+end
+
+task :build => :clean do
+  Dir.chdir(ROOT_DIR) do
+    sh "gem build restfully.gemspec"
+  end
+end
+
+task :install => :build do
+  Dir.chdir(ROOT_DIR) do
+    sh "gem install #{Dir["*.gem"].last}"
+  end
+end

data/bin/restfully

@@ -10,35 +10,39 @@ require 'logger'
 require 'pp'
 
 
-logger = Logger.new(STDOUT)
+logger = Logger.new(STDERR)
 logger.level = Logger::WARN
-@options = {:logger => logger}
+@options = {"logger" => logger, "require" => []}
+
 option_parser = OptionParser.new do |opts|
   opts.banner = <<BANNER
 * Description
   Restfully #{Restfully::VERSION} - Access REST APIs effortlessly
 * Usage
-  restfully [base_uri] [options]
+  restfully [uri] [options]
 * Options
 BANNER
 
   opts.on("-u=", "--username=", "Sets the username") do |u|
-    @options[:username] = u
+    @options["username"] = u
   end
   opts.on("-p=", "--password=", "Sets the user password") do |p|
-    @options[:password] = p
+    @options["password"] = p
   end
   opts.on("-c=", "--config=", "Sets the various options based on a custom YAML configuration file") do |v|
-    @options[:configuration_file] = v
+    @options["configuration_file"] = v
+  end
+  opts.on("-r=", "--require=", "Require an additional media-type") do |v|
+    @options["require"].push(v)
   end
   opts.on("--log=", "Outputs log messages to the given file. Defaults to stdout") do |v|
     original_logger_level = logger.level
     logger = Logger.new(File.expand_path(v))
     logger.level = original_logger_level
-    @options[:logger] = logger
+    @options["logger"] = logger
   end
   opts.on("-v", "--verbose", "Run verbosely") do |v|
-    @options[:logger].level = Logger::DEBUG
+    @options["logger"].level = Logger::DEBUG
   end
   opts.on_tail("-h", "--help", "Show this message") do
     puts opts
@@ -49,10 +53,29 @@ end
 
 option_parser.parse!
 
-@options[:base_uri] = ARGV.shift
+if @options["configuration_file"]
+  @options.merge!(YAML.load_file(
+    File.expand_path(@options["configuration_file"])
+  ))
+end
+
+@options["require"].each do |r|
+  logger.info "Requiring #{r} media-type..."
+  require "restfully/media_type/#{r.underscore}"
+end
+
+if given_uri = ARGV.shift
+  @options["uri"] = given_uri
+end
+# p @options
+# Compatibility with restfully < 0.6
+@options["uri"] ||= @options.delete("base_uri")
+
+@session = Restfully::Session.new(@options)
+
 
 def session
-  @session ||= Restfully::Session.new(@options)
+  @session
 end
 
 def root 
@@ -63,6 +86,41 @@ puts "Restfully/#{Restfully::VERSION} - The root resource is available in the 'r
 
 require 'irb'
 require 'irb/completion'
+require 'irb/ext/save-history'
+
+HOME = ENV['HOME'] || ENV['HOMEPATH']
+# Keep history of your last commands.
+# Taken from <http://blog.nicksieger.com/articles/2006/04/23/tweaking-irb>
+IRB.conf[:SAVE_HISTORY] = 100
+IRB.conf[:HISTORY_FILE] = "#{HOME}/.irb-save-history"
+
+module Readline
+  module History
+    LOG = "#{HOME}/.irb-history"
+
+    def self.write_log(line)
+      File.open(LOG, 'ab') {|f| 
+        f << "#{line}\n"
+      }
+    end
+    
+    def self.start_session_log
+      write_log("\n")
+    end
+  end
+
+  alias :old_readline :readline
+  def readline(*args)
+    ln = old_readline(*args)
+    begin
+      History.write_log(ln)
+    rescue
+    end
+    ln
+  end
+end
+Readline::History.start_session_log
 ARGV.clear
+ARGV.concat [ "--readline", "--prompt-mode", "simple" ]
 IRB.start
 exit!

data/lib/restfully.rb

@@ -1,24 +1,18 @@
 require 'backports'
 require 'yaml'
-require 'restfully/extensions'
+
+require 'restfully/version'
 require 'restfully/error'
-require 'restfully/parsing'
 require 'restfully/http'
-require 'restfully/http/adapters/rest_client_adapter'
-require 'restfully/session'
-require 'restfully/special_hash'
-require 'restfully/special_array'
 require 'restfully/link'
 require 'restfully/resource'
 require 'restfully/collection'
+require 'restfully/rack'
+require 'restfully/session'
+require 'restfully/media_type'
 
 module Restfully
-  # To be changed on version bump
-  VERSION = "0.6.3"
-  
-  class << self
-    attr_accessor :adapter
-  end
-  
-  self.adapter = Restfully::HTTP::Adapters::RestClientAdapter
+  MediaType.register MediaType::Grid5000
+  MediaType.register MediaType::ApplicationJson
+  MediaType.register MediaType::Wildcard
 end

data/lib/restfully/collection.rb

@@ -1,111 +1,91 @@
-
 module Restfully
-  # This includes the <tt>Enumerable</tt> module, but does not have all the
-  # methods that you could expect from an <tt>Array</tt>.
-  # Remember that this class inherits from a <tt>Restfully::Resource</tt> and
-  # as such, the <tt>#[]</tt> method gives access to Resource properties, and
-  # not to an item in the collection.
-  # If you want to operate on the array of items, you MUST call <tt>#to_a</tt>
-  # first (or <tt>#items</tt>) on the Restfully::Collection.
-  class Collection < Resource
+  module Collection
     include Enumerable
-    attr_reader :items
-    
-    # See Resource#new
-    def initialize(uri, session, options = {})
-      super(uri, session, options)
-    end
 
-    # See Resource#reset
-    def reset
-      super
-      @items = Array.new
-      @indexes = Hash.new
-      self
-    end
-    
-    # Iterates over the collection of items
-    def each(*args, &block)
-      @items.each_index{ |i|
-        block.call(@items[i])
-        if i == @items.length-1 && @items.length+self["offset"] < self["total"]
-          # load next page
-          query_options = executed_requests['GET']['options'][:query] || {}
-          query_options[:offset] = self["offset"]+@items.length
-          query_options[:limit] ||= 200
-          next_page = Collection.new(uri, session).load(:query => query_options) rescue nil
-          if next_page && next_page['offset'] != self["offset"]
-            @items.push(*next_page.to_a)
-          end
-        end
-      }
-    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.
+    # If property is a Symbol, it tries to find the corresponding item in the collection.
+    # Else, returns the result of calling <tt>[]</tt> on its superclass.
     def [](property)
-      if property.kind_of?(Symbol)
-        item = find{|i| i['uid'] == property.to_s} || 
-          find{|i| i['uid'] == property.to_s.to_i} ||
-          Resource.new([uri, property].join("/"), session).load rescue nil
+      case property
+      when Symbol
+        find_by_uid(property)
+      when Integer
+        find_by_index(property)
       else
         super(property)
       end
     end
     
-    # Returns the current number of items (not the total number) 
-    # in the collection.
-    def length
-      @items.length
+    def find_by_uid(symbol)
+      find{ |i| reload_if_empty(i).media_type.represents?(symbol) }
+    end
+    
+    def find_by_index(index)
+      index = index+length if index < 0
+      each_with_index{|item, i|
+        return reload_if_empty(item) if i == index
+      }
+      nil
     end
 
-    def populate_object(key, value)
-      case key
-      when "links"
-        value.each{|link| define_link(Link.new(link))}
-      when "items"
-        value.each do |item|
-          self_link = (item['links'] || []).
-            map{|link| Link.new(link)}.detect{|link| link.self?}
-          if self_link && self_link.valid?
-            @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
-        end
-      else
-        case value
-        when Hash
-          @properties.store(key, SpecialHash.new.replace(value)) unless @links.has_key?(key)
-        when Array
-          @properties.store(key, SpecialArray.new(value))
-        else
-          @properties.store(key, value)
+    def each(*args, &block)
+      @items ||= {}
+      media_type.each(*args) do |item_media_type|
+        hash = item_media_type.hash
+        unless @items.has_key?(hash)
+          self_link = item_media_type.links.find{|l| l.self?}
+
+          req = HTTP::Request.new(session, :get, self_link.href, :head => {
+            'Accept' => self_link.types[0]
+          })
+
+          res = HTTP::Response.new(session, 200, {
+            'Content-Type' => self_link.types[0]
+          }, item_media_type.io)
+          @items[hash] = Resource.new(session, res, req).load
         end
+        block.call @items[hash]
       end
-    end    
+    end
 
-    def inspect
-      @items.inspect
+    def length
+      self["items"].length
     end
 
+    def total
+      self["total"].to_i
+    end
+
+    def offset
+      (self["offset"] || 0).to_i
+    end
+
+    def last
+      self[-1]
+    end
+
+    def empty?
+      total == 0
+    end
     
-    def pretty_print(pp)
-      super(pp) do |inner_pp|
-        if @items.length > 0
-          inner_pp.breakable
-          inner_pp.text "ITEMS (#{self["offset"]}..#{self["offset"]+@items.length})/#{self["total"]}"
-          inner_pp.nest 2 do
-            @items.each_with_index do |item, i|
-              inner_pp.breakable
-              inner_pp.text "#<#{item.class}:0x#{item.object_id.to_s(16)} uid=#{item['uid'].inspect}>"            
-              inner_pp.text "," if i < @items.length-1
-            end
-          end
-        end
-      end
+    def inspect
+      map{|item| item}.inspect
     end
+    # def (key)
+    #   p Addressable::URI.parse("./"+key.to_s)
+    #   p self.uri
+    #   uri_to_find = Addressable::URI.join(self.uri, "./"+key.to_s)
+    #   p uri_to_find
+    #   find{|resource|
+    #     resource.uri == uri_to_find
+    #   }
+    # end
     
-    alias_method :size, :length
+    protected
+    def reload_if_empty(resource)
+      resource.reload if resource && !resource.media_type.complete?
+      resource
+    end
+
   end
+
 end