rest-client--rest-client/README.rdoc

= REST Client -- simple DSL for accessing REST resources

A simple REST client for Ruby, inspired by the Sinatra's microframework style
of specifying actions: get, put, post, delete.

== Usage: Raw URL

  require 'rest_client'

  RestClient.get 'http://example.com/resource'
  RestClient.get 'https://user:password@example.com/private/resource'

  RestClient.post 'http://example.com/resource', :param1 => 'one', :nested => { :param2 => 'two' }

  RestClient.delete 'http://example.com/resource'
  
== Multipart

Yeah, that's right!  This does multipart sends for you!

  RestClient.post '/data', :myfile => File.new("/path/to/image.jpg")

This does two things for you:

* Auto-detects that you have a File value sends it as multipart
* Auto-detects the mime of the file and sets it in the HEAD of the payload for each entry

If you are sending params that do not contain a File object but the payload needs to be multipart then:

  RestClient.post '/data', :foo => 'bar', :multipart => true

== Streaming downloads

  RestClient.get('http://some/resource/lotsofdata') do |res|
    res.read_body do |chunk|
      .. do something with chunk ..
    end
  end

See RestClient module docs for more details.

== Usage: ActiveResource-Style

  resource = RestClient::Resource.new 'http://example.com/resource'
  resource.get

  private_resource = RestClient::Resource.new 'https://example.com/private/resource', 'user', 'pass'
  private_resource.put File.read('pic.jpg'), :content_type => 'image/jpg'

See RestClient::Resource module docs for details.

== Usage: Resource Nesting

  site = RestClient::Resource.new('http://example.com')
  site['posts/1/comments'].post 'Good article.', :content_type => 'text/plain'

See RestClient::Resource docs for details.

== Lower-level access

For cases not covered by the general API,  you can use the Request class which provide a lower-level API, see the class' rdoc for more information.

== Shell

The restclient shell command gives an IRB session with RestClient already loaded:

  $ restclient
  >> RestClient.get 'http://example.com'

Specify a URL argument for get/post/put/delete on that resource:

  $ restclient http://example.com
  >> put '/resource', 'data'

Add a user and password for authenticated resources:

  $ restclient https://example.com user pass
  >> delete '/private/resource'

Create ~/.restclient for named sessions:

  sinatra:
    url: http://localhost:4567
  rack:
    url: http://localhost:9292
  private_site:
    url: http://example.com
    username: user
    password: pass

Then invoke:

  $ restclient private_site
  
== Meta

Written by Adam Wiggins (adam at heroku dot com)

Major modifications by Blake Mizerany

Patches contributed by: Chris Anderson, Greg Borenstein, Ardekantur, Pedro Belo, Rafael Souza, Rick Olson, Aman Gupta, François Beausoleil and Nick Plante.

Released under the MIT License: http://www.opensource.org/licenses/mit-license.php

http://rest-client.heroku.com

http://github.com/adamwiggins/rest-client

Mailing list: rest.client@librelist.com (send a mail to subscribe).

== Fork goal

This fork has several goals:
* merge the features of françois' version (http://github.com/francois/rest-client) into the original gem with as much as compatibility as possible
* improve the documentation for advanced features
* added some tests to the streaming and multipart features
* establish a users mailing list at rest.client@librelist.com
* avoid overall refactoring