= 'rufus-verbs'

== what is it ?

'rufus-verbs' is an extended HTTP client library (gem). It provides the four main HTTP "verbs" as Ruby methods : get, put, post and delete.

It wraps a certain number of techniques that make it a decent tool for manipulating web resources.


== features

currently :

* follows redirections
* automatically adds _method={post|put} in the request parameters with the option :fake_put => true
* HTTPS aware ('verify none' by default)
* HTTP basic authentication
* doesn't propagate auth credentials in case of redirection to different host
* advertises and uses gzip compression
* proxy-aware (HTTP_PROXY env var or :proxy option)
* conditional GET (via ConditionalEndPoint class)
* request body built via a block (post and put)

maybe later :

* retry on failure
* greediness (automatic parsing for content like JSON or YAML)
* http digest authentication
* cache awareness
* head, options


== getting it

    sudo gem install -y rufus-verbs

or download[http://rubyforge.org/frs/?group_id=4812] it from RubyForge.


== usage

The arguments to the "verbs" follow the schema <tt>method_name(uri, opts)</tt> or <tt>method_name(opts)</tt>. Post and put accept an optional block parameter.

    require 'rubygems'
    require 'rufus/verbs'

    include Rufus::Verbs

using get(), post(), put() and delete() directly

    res = get "http://en.wikipedia.org/wiki/Ruby"
    puts res.body

    res = get :uri => "http://en.wikipedia.org/wiki/Ruby"
    puts res.body

    post "http://resta.farian.server:7080/inventory/tools/0", :d => "hammer"
        # passing the data via the :d (or :data) option
    
    res = post "http://resta.farian.server:7080/inventory/tools/1" do
        "sliver bullet"
    end
        # the data is generated by a block

    puts res.code.to_i
        # 201... resource created, note that by default, 
        # an instance of Net::HTTPResponse is returned

    puts get("http://resta.farian.server:7080/inventory/tools/0", :body => true)
        # "sliver bullet" (directly returning the content of the response)

    # oops, typo

    put "http://resta.farian.server:7080/inventory/tools/1" do
        "silver bullet"
    end

    put "http://resta.farian.server:7080/inventory/tools/1" do |request|
        request['Content-Type'] = "text/plain"
        "no silver bullet"
    end
        # the block accepts a 'request' (Net::HTTPREquest) argument

    delete "http://resta.farian.server:7080/inventory/tools/0"
        # I don't need that hammer anymore


Using get() and co via an EndPoint to share common options for a set of requests

    ep = EndPoint.new :host => "resta.farian.host", :port => 7080, :resource => "inventory/tools"

    res = ep.get :id => 1
        # still a silver bullet ?

    res = ep.get :id => 0
        # where did the hammer go ?


A ConditionalEndPoint is an EndPoint that will use conditional GETs whenever possible

    ep = ConditionalEndPoint.new :host => "resta.farian.zion", :port => 7080, :resource => "inventory/tools"

    res = ep.get :id => 1
        # first call will retrieve the representation completely

    res = ep.get :id => 1
        # the server (provided that it supports conditional GET) only 
        # returned a 304 answer, the response is returned from the
        # ConditionalEndPoint cache

More about conditional GETs at http://ruturajv.wordpress.com/2005/12/27/conditional-get-request/

The tests may provide good intel as on 'rufus-verbs' usage as well : http://rufus.rubyforge.org/svn/trunk/verbs/test/


== the options

A list of options supported by rufus-verbs, in alphabetical order.

Most of the options are, well, optional, see the usage for some clarifications about the preseance of the options among them (trying to do it in the 'least surprise' spirit).

R means that the option can be used at request level only, RE means Request or EndPoint level.


* <b>:auth</b> (proc, RE)
this option takes a Ruby proc, it can be used for custom authentication schemes

    get "http://resource:7777/items/1", :auth => lambda do |request|
        request['X-Secret-Auth-Header'] = "let me in, it's OK"
    end

see :http_basic_authentication for the basic HTTP authentication mechanism

* <b>:base</b> (string, RE)
the base of a resource path

    :base / :resource / :id --> 
    "inventory" / "tools" / "7" --> 
    "/inventory/tools/7"

* <b>:body</b> (boolean, RE)
by default, a request returns a Net::HTTPResponse instance, with :body => true, the request will return the body of response directly

* <b>:cache_size</b> (integer, ConditionalEndPoint only)
by default, a ConditionalEndPoint will cache 147 results (and it'll start discarded the least recently used cached responses). This option is used to set this cache's size.

* <b>:d</b> (string, R)
the short variant of :data

* <b>:data</b> (string, R)
the data (request body) for a put or a post.

* <b>:dry_run</b> (boolean, RE) 
when <tt>:dry_run => true</tt>, the request will be prepared but not executed and will be returned instead of the HTTP response (used for testing)

* <b>:fake_put</b> (boolean, RE)
when set to true, PUT and DELETE requests will be faked as POST requests where the _method query parameter is set to 'put' or 'delete' respectively

* <b>:fd</b>
the short version of :form_data

* <b>:form_data</b>
this option expects a hash. The (post or put) request body will then be built with this hash.

* <b>:hba</b> (pair, RE) 
short for :http_basic_authentication

* <b>:host</b> (string, RE)
the host or IP address for the request

* <b>:http_basic_authentication</b> (pair, RE)
will activate HTTP basic authentication, takes a pair (array) argument [ user, pass ]

* <b>:id</b> (string, R)
the id part of a full resource path (see :base)

* <b>:max_redirections</b> (integer, RE)
by default, rufus-verbs will follow any number of redirections. A limit can be set via this option

* <b>:nozip</b> (boolean, RE)
if set to true will prevent gzip encoding (advertising) when GETting content

* <b>:path</b> (string, RE)
the path (between port and the query string)

* <b>:port</b> (string, RE)
the port for the request

* <b>:proxy</b> (uri, string or false, RE)
by default, rufus-verbs will try to use the proxy given in the HTTP_PROXY environment variable (URI). If this :proxy option is set to false, no proxy will be used. It can take the value of a URI (String or URI instance) as well.

* <b>:query</b> (hash or string, R)
a hash of parameters that will get appended to the URI of the request. A string like "a=b?x=y" can be given as well

* <b>:raw_response</b> (boolean, RE)
the request will be executed and the HTTP response will be returned immediately, no redirection following, content decompression or eventual caching (conditional GET) will take place

* <b>:res</b> (string, RE)
a short version of :resource

* <b>:resource</b>
the resource (or the middle) of a full resource path (see :base)

* <b>:scheme</b> (string, R)
'http' or 'https'

* <b>:u</b> (uri, string, RE)
the short version of :uri

* <b>:uri</b> (uri, string, RE)
the URI for the request (or the endpoint)

* <b>:user_agent</b> (string, RE)
for setting a custom 'User-Agent' HTTP header


== dependencies

the gem rufus-lru[http://rufus.rubyforge.org/rufus-lru]


== mailing list

On the OpenWFEru-user list[http://groups.google.com/group/openwferu-users] for now :

    http://groups.google.com/group/openwferu-users

== issue tracker

    http://rubyforge.org/tracker/?atid=18584&group_id=4812&func=browse


== source

    svn checkout http://rufus.rubyforge.org/svn/trunk/verbs


== author

John Mettraux, jmettraux@gmail.com,
http://jmettraux.wordpress.com


== license

MIT