restfully 0.6.3 → 0.7.0.pre

data/README.rdoc

@@ -1,146 +0,0 @@
-= 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). 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
-
-== 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 <tt>root.link_name</tt>) and what properties are available (by calling <tt>root[property_name]</tt>).
-
-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:
-* <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.
-* 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.

data/TODO.rdoc

@@ -1,3 +0,0 @@
-* Detects methods allowed on a resource using the Allow HTTP header, and generate corresponding wrappers.
-* On a 406, detects accepted content based on a (custom) HTTP header, and retry (if possible) with another Accept header for which a parser is available.
-* Investigate the possibility of using a :include => {} when loading resources or collection so that Restfully prefetches the included associations (using threads or events).

data/VERSION

@@ -1 +0,0 @@
-0.6.3

data/examples/grid5000.rb

@@ -1,33 +0,0 @@
-require 'rubygems'
-$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
-require 'pp'
-
-require File.dirname(__FILE__)+'/../lib/restfully'
-
-logger = Logger.new(STDOUT)
-logger.level = Logger::WARN
-
-RestClient.log = 'stdout'
-
-# 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|
-      accu['hardware'][node_status['hardware_state']] = (accu['hardware'][node_status['hardware_state']] || 0) + 1
-      accu['system'][node_status['system_state']] = (accu['system'][node_status['system_state']] || 0) + 1
-      accu
-    } rescue {'hardware' => {}, 'system' => {}}
-    grid_stats['hardware'].merge!(site_stats['hardware']) { |key,oldval,newval| oldval+newval }
-    grid_stats['system'].merge!(site_stats['system']) { |key,oldval,newval| oldval+newval }
-    p [site['uid'], site_stats]
-  end
-  p [:total, grid_stats]
-  puts "Getting status of a few nodes in rennes:"
-  pp grid.sites.find{|s| s['uid'] == 'rennes'}.status(:query => {:only => ['paradent-1', 'paradent-10', 'paramount-3']})
-end

data/examples/scratch.rb

@@ -1,37 +0,0 @@
-m = MediaType.new('application/vnd.grid5000+json')
-m.parser = JSON
-
-class Grid5000MediaType < Restfully::MediaType
-  
-  class << self
-    def supports?(given_type)
-      if given_type.kind_of?(Restfully::MediaType)
-        given_type = given_type.type
-      end
-      case given_type
-      when Regexp
-        given_type =~ type
-      else
-        given_type == type.to_s || given_type =~ Regexp.new(type.to_s)
-      end
-    end
-  end
-  
-  
-end
-
-
-get 'https://api.grid5000.fr/sid/grid5000'
-type = 'application/vnd.grid5000+json'
-m = MediaType.find(type)
-if m.nil?
-  "does not know how to interpret #{type}"
-else
-  grid5000 = Resource.new(uri, links, properties)
-  grid5000.sites[:rennes]
-  
-  m.links
-  m.properties
-end
-
-

data/lib/restfully/extensions.rb

@@ -1,34 +0,0 @@
-class BasicObject #:nodoc:
-  instance_methods.each { |m| undef_method m unless m =~ /^__|instance_eval/ }
-end unless defined?(BasicObject)
-
-class Object
-  # Taken from ActiveSupport
-  def to_query(key)
-    require 'cgi' unless defined?(CGI) && defined?(CGI::escape)
-    "#{CGI.escape(key.to_s)}=#{CGI.escape(to_params.to_s)}"
-  end
-  
-  def to_params
-    to_s
-  end
-end
-
-class Hash
-  # Converts a hash into a string suitable for use as a URL query string. 
-  # An optional <tt>namespace</tt> can be passed to enclose the param names.
-  # Taken from ActiveSupport
-  def to_params(namespace = nil)
-    collect do |key, value|
-      value.to_query(namespace ? "#{namespace}[#{key}]" : key)
-    end * '&'
-  end
-end
-
-class Array
-  # Taken from ActiveSupport
-  def to_query(key)
-    prefix = "#{key}[]"
-    collect { |value| value.to_query(prefix) }.join '&'
-  end
-end

data/lib/restfully/http/adapters/abstract_adapter.rb

@@ -1,29 +0,0 @@
-module Restfully
-  module HTTP
-    module Adapters
-      
-      class AbstractAdapter
-        attr_reader :logger, :options
-        def initialize(base_uri, options = {})
-          @options = options.symbolize_keys
-          @logger = @options.delete(:logger) || Restfully::NullLogger.new
-          @base_uri = base_uri
-        end
-        
-        def get(request)
-          raise NotImplementedError, "GET is not supported by your adapter."
-        end
-        def post(request)
-          raise NotImplementedError, "POST is not supported by your adapter."
-        end
-        def put(request)
-          raise NotImplementedError, "PUT is not supported by your adapter."
-        end
-        def delete(request)
-          raise NotImplementedError, "DELETE is not supported by your adapter."
-        end
-      end
-      
-    end
-  end
-end

data/lib/restfully/http/adapters/patron_adapter.rb

@@ -1,16 +0,0 @@
-require 'restfully/http/adapters/abstract_adapter'
-require 'patron'
-
-module Restfully
-  module HTTP
-    module Adapters
-      class PatronAdapter < AbstractAdapter
-        
-        def initialize(base_url, options = {})
-          super(base_url, options)
-        end
-        
-      end
-    end
-  end
-end

data/lib/restfully/http/adapters/rest_client_adapter.rb

@@ -1,75 +0,0 @@
-require 'restfully/http/adapters/abstract_adapter'
-require 'restclient'
-
-module Restfully
-  module HTTP
-    module Adapters
-      class RestClientAdapter < AbstractAdapter
-        
-        def initialize(base_uri, options = {})
-          super(base_uri, options)
-          @options[:user] = @options.delete(:username)
-          RestClient.log = logger
-        end # def initialize
-        
-        def head(request)
-          in_order_to_get_the_response_to(request) do |resource|
-            resource.head(convert_header_keys_into_symbols(request.headers))
-          end
-        end # def head
-        
-        def get(request)
-          in_order_to_get_the_response_to(request) do |resource|
-            resource.get(convert_header_keys_into_symbols(request.headers))
-          end
-        end # def get
-        
-        def delete(request)
-          in_order_to_get_the_response_to(request) do |resource|
-            resource.delete(convert_header_keys_into_symbols(request.headers))
-          end
-        end # def delete
-        
-        def put(request)
-          in_order_to_get_the_response_to(request) do |resource|
-            resource.put(request.raw_body, convert_header_keys_into_symbols(request.headers))
-          end
-        end # def put
-        
-        def post(request)
-          in_order_to_get_the_response_to(request) do |resource|
-            resource.post(request.raw_body, convert_header_keys_into_symbols(request.headers))
-          end
-        end # def post
-        
-        protected
-        def in_order_to_get_the_response_to(request, &block)
-          begin
-            resource = RestClient::Resource.new(request.uri.to_s, @options)
-            response = block.call(resource)
-            headers = response.headers
-            body = response.to_s
-            headers.delete(:status)
-            status = response.code
-          rescue RestClient::ExceptionWithResponse => e
-            body = e.response.to_s
-            headers = e.response.headers rescue {}
-            status = e.http_code
-          end
-          Response.new(status, headers, body)
-        end # def in_order_to_get_the_response_to
-        
-        # there is a bug in RestClient, when passing headers whose keys are string that are already defined as default headers, they get overwritten.
-        def convert_header_keys_into_symbols(headers)
-          headers.inject({}) do |final, (key,value)|
-            key = key.to_s.gsub(/-/, "_").downcase.to_sym
-            final[key] = value
-            final
-          end
-        end # def convert_header_keys_into_symbols
-        
-      end
-    
-    end
-  end
-end

data/lib/restfully/http/headers.rb

@@ -1,20 +0,0 @@
-module Restfully
-  module HTTP
-    module Headers
-      def sanitize_http_headers(headers = {})
-        sanitized_headers = {}
-        headers.each do |key, value|
-          sanitized_key = key.to_s.downcase.gsub(/[_-]/, ' ').split(' ').map{|word| word.capitalize}.join("-")
-          sanitized_value = case value
-          when Array 
-            value.join(", ")
-          else 
-            value
-          end
-          sanitized_headers[sanitized_key] = sanitized_value
-        end
-        sanitized_headers
-      end
-    end
-  end
-end

data/lib/restfully/parsing.rb

@@ -1,66 +0,0 @@
-
-
-module Restfully
-  
-  module Parsing
-    
-    class ParserNotFound < Restfully::Error; end
-    
-    PARSERS = [
-      {
-        :supported_types => [/^application\/.*?json/i], 
-        :parse => lambda{|object, options| 
-          require 'json'
-          JSON.parse(object)
-        }, 
-        :dump => lambda{|object, options|
-          require 'json' 
-          JSON.dump(object)
-        },
-        :object => true
-      },
-      {
-        :supported_types => [/^text\/.*?(plain|html)/i], 
-        :parse => lambda{|object, options| object}, 
-        :dump => lambda{|object, options| object}
-      },
-      { # just store the binary data in a 'raw' property
-        :supported_types => ["application/zip"],
-        :parse => lambda{|object, options| {'raw' => object}},
-        :dump => lambda{|object, options| object['raw']}
-      }
-    ]
-    
-    def unserialize(object, options = {})
-      content_type = options[:content_type]
-      content_type ||= object.headers['Content-Type'] if object.respond_to?(:headers)
-      parser = select_parser_for(content_type)
-      if parser
-        parser[:parse].call(object, options)
-      else
-        raise ParserNotFound.new("Cannot find a parser to parse '#{content_type}' content.")
-      end
-    end
-  
-    def serialize(object, options = {})
-      content_type = options[:content_type]
-      content_type ||= object.headers['Content-Type'] if object.respond_to?(:headers)
-      parser = select_parser_for(content_type)
-      if parser
-        parser[:dump].call(object, options)
-      else
-        raise ParserNotFound.new("Cannot find a parser to dump object into '#{content_type}' content.")
-      end
-    end
-    
-    def select_parser_for(content_type)
-      raise ParserNotFound.new("The Content-Type HTTP header of the resource is empty. Cannot find a parser.") if content_type.nil? || content_type.empty?
-      content_type.split(",").each do |type|
-        parser = PARSERS.find{|parser| parser[:supported_types].find{|supported_type| type =~ (supported_type.kind_of?(String) ? Regexp.new(supported_type) : supported_type) }}
-        return parser unless parser.nil?
-      end
-      nil
-    end
-
-  end
-end