= '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)
* cookie-aware (if :cookies option is explicitely set to true)
* http digest authentication (rfc 2617) (auth ok, auth-int not tested)

maybe later :

* retry on failure
* cache awareness
* greediness (automatic parsing for content like JSON or YAML)
* head, options
* persistent cookie jar


== 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 GETs) 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/

Cookies may be activated for an endpoint in this way :

    ep = EndPoint.new :cookies => true

    res = ep.get "http://resta.farian.zion/tools/3"
    res = ep.post("http://resta.farian.zion/tools") { "hammer" }

Digest authentication and basic authentication are available at request or endpoint level :

    ep = EndPoint.new :http_basic_authentication => [ "toto", "secretpass" ]

    ep = EndPoint.new :digest_authentication => [ "toto", "secretpass" ]

    res = get "http://server/doc0", :hba => [ "toto", "secretpass" ]

    res = get "http://server/doc1", :digest_authentication => [ "toto", "secretpass" ]

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>:cookies</b> (boolean/integer, E)
when not set or set to false, rufus-verbs won't care about cookies. If set to true or an integer value, set-cookie requests by the servers will be honoured. The integer value will be interpreted as the size of the 'cookie jar', the default size being 77. The least recently used cookies will be discarded.
The cookie jar implementation is not persistent.

* <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>:digest_authentication</b> (pair of strings, RE)
the pair username/password to be used for digest authentication.

* <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 of strings, 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 of strings, 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>:no_redirections</b> (boolean, RE)
when set to 'true', redirections will not be followed, the server response will be returned directly, even if it's a redirection notification.

* <b>:noredir</b> (boolean, RE)
the short version for :no_redirections.

* <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>:ssl_verify_peer</b> (boolean, RE)
by default, rufus-verbs doesn't verify ssl certificates. With this option set to true, it will.

* <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 Rufus-Ruby list[http://groups.google.com/group/rufus-ruby] :

    http://groups.google.com/group/rufus-ruby


== 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