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

= REST Client -- simple DSL for accessing HTTP and REST resources

Build status: {<img src="https://travis-ci.org/rest-client/rest-client.svg?branch=master" alt="Build Status" />}[https://travis-ci.org/rest-client/rest-client]

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

* Main page: https://github.com/rest-client/rest-client
* Mailing list: rest.client@librelist.com (send a mail to subscribe).

== Requirements

MRI Ruby 1.9.2 and newer are supported. Alternative interpreters compatible with
1.9.1+ should work as well.

Ruby 1.8.7 is no longer supported.  That's because the Ruby 1.8.7 interpreter
itself no longer has official support, _not_ _even_ _security_ _patches!_ If you
have been putting off upgrading your servers, now is the time.
({More info is on the Ruby developers'
blog.}[http://www.ruby-lang.org/en/news/2013/06/30/we-retire-1-8-7/])

The rest-client gem depends on these other gems for installation and usage:

* {mime-types}[http://rubygems.org/gems/mime-types]
* {netrc}[http://rubygems.org/gems/netrc]
* {rdoc}[http://rubygems.org/gems/rdoc]

If you want to hack on the code, you should also have {the Bundler
gem}[http://bundler.io/] installed so it can manage all necessary development
dependencies for you.

== Usage: Raw URL

  require 'rest_client'

  RestClient.get 'http://example.com/resource'

  RestClient.get 'http://example.com/resource', {:params => {:id => 50, 'foo' => 'bar'}}

  RestClient.get 'https://user:password@example.com/private/resource', {:accept => :json}

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

  RestClient.post "http://example.com/resource", { 'x' => 1 }.to_json, :content_type => :json, :accept => :json

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

  response = RestClient.get 'http://example.com/resource'
  response.code
  ➔ 200
  response.cookies
  ➔ {"Foo"=>"BAR", "QUUX"=>"QUUUUX"}
  response.headers
  ➔ {:content_type=>"text/html; charset=utf-8", :cache_control=>"private" ...
  response.to_str
  ➔ \n<!DOCTYPE html PUBLIC \"-//W3C//DTD HTML 4.01//EN\"\n   \"http://www.w3.org/TR/html4/strict.dtd\">\n\n<html ....

  RestClient.post( url,
    {
      :transfer => {
        :path => '/foo/bar',
        :owner => 'that_guy',
        :group => 'those_guys'
      },
       :upload => {
        :file => File.new(path, 'rb')
      }
    })

== Multipart

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

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

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}

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

== Exceptions (see http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html)

* for result codes between 200 and 207, a RestClient::Response will be returned
* for result codes 301, 302 or 307, the redirection will be followed if the request is a GET or a HEAD
* for result code 303, the redirection will be followed and the request transformed into a GET
* for other cases, a RestClient::Exception holding the Response will be raised; a specific exception class will be thrown for known error codes

   RestClient.get 'http://example.com/resource'
   ➔ RestClient::ResourceNotFound: RestClient::ResourceNotFound

   begin
     RestClient.get 'http://example.com/resource'
   rescue => e
     e.response
   end
   ➔ 404 Resource Not Found | text/html 282 bytes

== Result handling

A block can be passed to the RestClient method. This block will then be called with the Response.
Response.return! can be called to invoke the default response's behavior.

  # Don't raise exceptions but return the response
  RestClient.get('http://example.com/resource'){|response, request, result| response }
  ➔ 404 Resource Not Found | text/html 282 bytes

  # Manage a specific error code
  RestClient.get('http://my-rest-service.com/resource'){ |response, request, result, &block|
    case response.code
    when 200
      p "It worked !"
      response
    when 423
      raise SomeCustomExceptionIfYouWant
    else
      response.return!(request, result, &block)
    end
  }

  # Follow redirections for all request types and not only for get and head
  # RFC : "If the 301, 302 or 307 status code is received in response to a request other than GET or HEAD,
  #        the user agent MUST NOT automatically redirect the request unless it can be confirmed by the user,
  #        since this might change the conditions under which the request was issued."
  RestClient.get('http://my-rest-service.com/resource'){ |response, request, result, &block|
    if [301, 302, 307].include? response.code
      response.follow_redirection(request, result, &block)
    else
      response.return!(request, result, &block)
    end
  }

== Non-normalized URIs

If you need to normalize URIs, e.g. to work with International Resource Identifiers (IRIs),
use the addressable gem (http://addressable.rubyforge.org/api/) in your code:

  require 'addressable/uri'
  RestClient.get(Addressable::URI.parse("http://www.詹姆斯.com/").normalize.to_str)

== Lower-level access

For cases not covered by the general API, you can use the RestClient::Request class, which provides a lower-level API.

You can:

* specify ssl parameters
* override cookies
* manually handle the response (e.g. to operate on it as a stream rather than reading it all into memory)

See RestClient::Request's documentation 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

Use as a one-off, curl-style:

  $ restclient get http://example.com/resource > output_body

  $ restclient put http://example.com/resource < input_body

== Logging

To enable logging you can:

* set RestClient.log with a Ruby Logger, or
* set an environment variable to avoid modifying the code (in this case you can use a file name, "stdout" or "stderr"):

   $ RESTCLIENT_LOG=stdout path/to/my/program

Either produces logs like this:

  RestClient.get "http://some/resource"
  # => 200 OK | text/html 250 bytes
  RestClient.put "http://some/resource", "payload"
  # => 401 Unauthorized | application/xml 340 bytes

Note that these logs are valid Ruby, so you can paste them into the restclient
shell or a script to replay your sequence of rest calls.

== Proxy

All calls to RestClient, including Resources, will use the proxy specified by
RestClient.proxy:

  RestClient.proxy = "http://proxy.example.com/"
  RestClient.get "http://some/resource"
  # => response from some/resource as proxied through proxy.example.com

Often the proxy URL is set in an environment variable, so you can do this to
use whatever proxy the system is configured to use:

  RestClient.proxy = ENV['http_proxy']

== Query parameters

Request objects know about query parameters and will automatically add them to
the URL for GET, HEAD and DELETE requests, escaping the keys and values as needed:

  RestClient.get 'http://example.com/resource', :params => {:foo => 'bar', :baz => 'qux'}
  # will GET http://example.com/resource?foo=bar&baz=qux

== Cookies

Request and Response objects know about HTTP cookies, and will automatically
extract and set headers for them as needed:

  response = RestClient.get 'http://example.com/action_which_sets_session_id'
  response.cookies
  # => {"_applicatioN_session_id" => "1234"}

  response2 = RestClient.post(
    'http://localhost:3000/',
    {:param1 => "foo"},
    {:cookies => {:session_id => "1234"}}
  )
  # ...response body

== SSL Client Certificates

  RestClient::Resource.new(
    'https://example.com',
    :ssl_client_cert  =>  OpenSSL::X509::Certificate.new(File.read("cert.pem")),
    :ssl_client_key   =>  OpenSSL::PKey::RSA.new(File.read("key.pem"), "passphrase, if any"),
    :ssl_ca_file      =>  "ca_certificate.pem",
    :verify_ssl       =>  OpenSSL::SSL::VERIFY_PEER
  ).get

Self-signed certificates can be generated with the openssl command-line tool.

== Hook

RestClient.add_before_execution_proc add a Proc to be called before each execution.
It's handy if you need direct access to the HTTP request.

Example:

  # Add oauth support using the oauth gem
  require 'oauth'
  access_token = ...

  RestClient.add_before_execution_proc do |req, params|
    access_token.sign! req
  end

  RestClient.get 'http://example.com'

== More

Need caching, more advanced logging or any ability provided by Rack middleware?

Have a look at rest-client-components: http://github.com/crohr/rest-client-components

== Credits

REST Client Team:: Matthew Manning, Lawrence Leonard Gilbert, Andy Brody

Creator:: Adam Wiggins

Maintainer Emeritus:: Julien Kirch

Major contributions:: Blake Mizerany, Julien Kirch

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

== Legal

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

"Master Shake" photo (http://www.flickr.com/photos/solgrundy/924205581/) by
"SolGrundy"; used under terms of the Creative Commons Attribution-ShareAlike 2.0
Generic license (http://creativecommons.org/licenses/by-sa/2.0/)

Code for reading Windows root certificate store derived from work by Puppet;
used under terms of the Apache License, Version 2.0.
Added a part about URI normalization 2010-01-24 10:04:31 -05:00			`= REST Client -- simple DSL for accessing HTTP and REST resources`
README and some rdoc comments 2008-03-09 16:25:18 -04:00
Switch to SVG build status. 2014-07-08 03:25:21 -04:00			`Build status: {<img src="https://travis-ci.org/rest-client/rest-client.svg?branch=master" alt="Build Status" />}[https://travis-ci.org/rest-client/rest-client]`
Added a travis ci build file 2013-02-19 08:25:41 -05:00
Added a part about URI normalization 2010-01-24 10:04:31 -05:00			`A simple HTTP and REST client for Ruby, inspired by the Sinatra's microframework style`
shorten readme summary 2008-06-21 00:09:44 -04:00			`of specifying actions: get, put, post, delete.`
README and some rdoc comments 2008-03-09 16:25:18 -04:00
Use https link for homepage. 2014-04-25 21:24:00 -04:00			`* Main page: https://github.com/rest-client/rest-client`
Put contact info at the beginning 2010-04-30 12:34:35 -04:00			`* Mailing list: rest.client@librelist.com (send a mail to subscribe).`

Add requirements section to README This includes a new admonition against using Ruby 1.8.7. [ci skip] 2013-08-19 11:21:48 -04:00			`== Requirements`

			`MRI Ruby 1.9.2 and newer are supported. Alternative interpreters compatible with`
			`1.9.1+ should work as well.`

			`Ruby 1.8.7 is no longer supported. That's because the Ruby 1.8.7 interpreter`
			`itself no longer has official support, _not_ _even_ _security_ _patches!_ If you`
			`have been putting off upgrading your servers, now is the time.`
			`({More info is on the Ruby developers'`
			`blog.}[http://www.ruby-lang.org/en/news/2013/06/30/we-retire-1-8-7/])`

			`The rest-client gem depends on these other gems for installation and usage:`

			`* {mime-types}[http://rubygems.org/gems/mime-types]`
			`* {netrc}[http://rubygems.org/gems/netrc]`
			`* {rdoc}[http://rubygems.org/gems/rdoc]`

			`If you want to hack on the code, you should also have {the Bundler`
			`gem}[http://bundler.io/] installed so it can manage all necessary development`
			`dependencies for you.`

Rollback, still doesn't work 2009-12-26 09:51:47 -05:00			`== Usage: Raw URL`
README and some rdoc comments 2008-03-09 16:25:18 -04:00
rdocs 2008-03-09 16:31:52 -04:00			`require 'rest_client'`
README and some rdoc comments 2008-03-09 16:25:18 -04:00
lighten readme by moving detailed docs to restclient module 2008-08-01 14:39:24 -04:00			`RestClient.get 'http://example.com/resource'`
adding :block_response parameter 2010-12-07 13:50:54 -05:00
separated params get example from https example 2010-05-31 13:56:41 -04:00			`RestClient.get 'http://example.com/resource', {:params => {:id => 50, 'foo' => 'bar'}}`

			`RestClient.get 'https://user:password@example.com/private/resource', {:accept => :json}`
README and some rdoc comments 2008-03-09 16:25:18 -04:00
lighten readme by moving detailed docs to restclient module 2008-08-01 14:39:24 -04:00			`RestClient.post 'http://example.com/resource', :param1 => 'one', :nested => { :param2 => 'two' }`
update readme with more examples 2008-06-21 00:07:20 -04:00
Specify accept and content-type as extension + we now log the real headers 2009-12-29 14:30:38 -05:00			`RestClient.post "http://example.com/resource", { 'x' => 1 }.to_json, :content_type => :json, :accept => :json`

update readme with more examples 2008-06-21 00:07:20 -04:00			`RestClient.delete 'http://example.com/resource'`
response are now string and response is a module 2010-03-29 13:38:23 -04:00
			`response = RestClient.get 'http://example.com/resource'`
			`response.code`
			`➔ 200`
			`response.cookies`
			`➔ {"Foo"=>"BAR", "QUUX"=>"QUUUUX"}`
			`response.headers`
shorted lines 2010-03-29 13:39:48 -04:00			`➔ {:content_type=>"text/html; charset=utf-8", :cache_control=>"private" ...`
response are now string and response is a module 2010-03-29 13:38:23 -04:00			`response.to_str`
			`➔ \n<!DOCTYPE html PUBLIC \"-//W3C//DTD HTML 4.01//EN\"\n \"http://www.w3.org/TR/html4/strict.dtd\">\n\n<html ....`
add a rails-like usage example 2010-04-12 07:27:00 -04:00
			`RestClient.post( url,`
			`{`
			`:transfer => {`
			`:path => '/foo/bar',`
			`:owner => 'that_guy',`
			`:group => 'those_guys'`
			`},`
			`:upload => {`
use File.new(XXX, "rb") in README so examples will work on windows 2010-05-10 12:33:12 -04:00			`:file => File.new(path, 'rb')`
add a rails-like usage example 2010-04-12 07:27:00 -04:00			`}`
			`})`
Rollback, still doesn't work 2009-12-26 09:51:47 -05:00
			`== Multipart`
README and some rdoc comments 2008-03-09 16:25:18 -04:00
Multipart with Streaming 2008-07-23 16:16:05 -04:00			`Yeah, that's right! This does multipart sends for you!`

use File.new(XXX, "rb") in README so examples will work on windows 2010-05-10 12:33:12 -04:00			`RestClient.post '/data', :myfile => File.new("/path/to/image.jpg", 'rb')`
Multipart with Streaming 2008-07-23 16:16:05 -04:00
			`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:`

fix multipart request syntax see https://github.com/archiloque/rest-client/blob/master/lib/restclient/payload.rb#L15 2011-10-24 12:17:18 -04:00			`RestClient.post '/data', {:foo => 'bar', :multipart => true}`
Multipart with Streaming 2008-07-23 16:16:05 -04:00
Rollback, still doesn't work 2009-12-26 09:51:47 -05:00			`== Usage: ActiveResource-Style`
RestClient::Resource 2008-03-10 20:20:57 -04:00
update readme with more examples 2008-06-21 00:07:20 -04:00			`resource = RestClient::Resource.new 'http://example.com/resource'`
RestClient::Resource 2008-03-10 20:20:57 -04:00			`resource.get`

expand shell docs 2008-07-20 16:13:16 -04:00			`private_resource = RestClient::Resource.new 'https://example.com/private/resource', 'user', 'pass'`
update readme with more examples 2008-06-21 00:07:20 -04:00			`private_resource.put File.read('pic.jpg'), :content_type => 'image/jpg'`
RestClient::Resource 2008-03-10 20:20:57 -04:00
doesn't work with gihub markdown 2009-12-20 10:20:30 -05:00			`See RestClient::Resource module docs for details.`
RestClient::Resource 2008-03-10 20:20:57 -04:00
Rollback, still doesn't work 2009-12-26 09:51:47 -05:00			`== Usage: Resource Nesting`
update readme with more examples 2008-06-21 00:07:20 -04:00
			`site = RestClient::Resource.new('http://example.com')`
			`site['posts/1/comments'].post 'Good article.', :content_type => 'text/plain'`

			`See RestClient::Resource docs for details.`

Fix 303 2010-02-10 15:48:46 -05:00			`== Exceptions (see http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html)`
Block for response done, easier than expected! 2010-01-22 15:04:49 -05:00
Copy-edit README 2013-08-04 16:34:25 -04:00			`* for result codes between 200 and 207, a RestClient::Response will be returned`
			`* for result codes 301, 302 or 307, the redirection will be followed if the request is a GET or a HEAD`
			`* for result code 303, the redirection will be followed and the request transformed into a GET`
			`* for other cases, a RestClient::Exception holding the Response will be raised; a specific exception class will be thrown for known error codes`
Block for response done, easier than expected! 2010-01-22 15:04:49 -05:00
			`RestClient.get 'http://example.com/resource'`
			`➔ RestClient::ResourceNotFound: RestClient::ResourceNotFound`

			`begin`
			`RestClient.get 'http://example.com/resource'`
			`rescue => e`
			`e.response`
			`end`
Updated README to match with Response refactoring 2010-02-01 12:12:21 -05:00			`➔ 404 Resource Not Found \| text/html 282 bytes`
Block for response done, easier than expected! 2010-01-22 15:04:49 -05:00
			`== Result handling`

Copy-edit README 2013-08-04 16:34:25 -04:00			`A block can be passed to the RestClient method. This block will then be called with the Response.`
Fixed redirection, and move the code to Response 2010-02-10 15:31:59 -05:00			`Response.return! can be called to invoke the default response's behavior.`
Block for response done, easier than expected! 2010-01-22 15:04:49 -05:00
			`# Don't raise exceptions but return the response`
Cookies set in a response should be kept in a redirect. Closes #38 2010-07-04 14:36:16 -04:00			`RestClient.get('http://example.com/resource'){\|response, request, result\| response }`
Updated README to match with Response refactoring 2010-02-01 12:12:21 -05:00			`➔ 404 Resource Not Found \| text/html 282 bytes`
Block for response done, easier than expected! 2010-01-22 15:04:49 -05:00
			`# Manage a specific error code`
Cookies set in a response should be kept in a redirect. Closes #38 2010-07-04 14:36:16 -04:00			`RestClient.get('http://my-rest-service.com/resource'){ \|response, request, result, &block\|`
Block for response done, easier than expected! 2010-01-22 15:04:49 -05:00			`case response.code`
			`when 200`
			`p "It worked !"`
			`response`
			`when 423`
			`raise SomeCustomExceptionIfYouWant`
			`else`
Cookies set in a response should be kept in a redirect. Closes #38 2010-07-04 14:36:16 -04:00			`response.return!(request, result, &block)`
Fixed redirection, and move the code to Response 2010-02-10 15:31:59 -05:00			`end`
			`}`

			`# Follow redirections for all request types and not only for get and head`
added 307 2010-05-25 12:55:57 -04:00			`# RFC : "If the 301, 302 or 307 status code is received in response to a request other than GET or HEAD,`
Another fix on README + added rfc quote 2010-02-10 15:55:26 -05:00			`# the user agent MUST NOT automatically redirect the request unless it can be confirmed by the user,`
			`# since this might change the conditions under which the request was issued."`
Cookies set in a response should be kept in a redirect. Closes #38 2010-07-04 14:36:16 -04:00			`RestClient.get('http://my-rest-service.com/resource'){ \|response, request, result, &block\|`
added 307 2010-05-25 12:55:57 -04:00			`if [301, 302, 307].include? response.code`
Cookies set in a response should be kept in a redirect. Closes #38 2010-07-04 14:36:16 -04:00			`response.follow_redirection(request, result, &block)`
Fixed redirection, and move the code to Response 2010-02-10 15:31:59 -05:00			`else`
Cookies set in a response should be kept in a redirect. Closes #38 2010-07-04 14:36:16 -04:00			`response.return!(request, result, &block)`
Block for response done, easier than expected! 2010-01-22 15:04:49 -05:00			`end`
			`}`

Copy-edit README 2013-08-04 16:34:25 -04:00			`== Non-normalized URIs`
Added a part about URI normalization 2010-01-24 10:04:31 -05:00
Copy-edit README 2013-08-04 16:34:25 -04:00			`If you need to normalize URIs, e.g. to work with International Resource Identifiers (IRIs),`
			`use the addressable gem (http://addressable.rubyforge.org/api/) in your code:`
Added a part about URI normalization 2010-01-24 10:04:31 -05:00
			`require 'addressable/uri'`
			`RestClient.get(Addressable::URI.parse("http://www.詹姆斯.com/").normalize.to_str)`

Rollback, still doesn't work 2009-12-26 09:51:47 -05:00			`== Lower-level access`
Link to Request class, so the rdoc will be usefull. 2009-12-17 15:27:40 -05:00
Copy-edit README 2013-08-04 16:34:25 -04:00			`For cases not covered by the general API, you can use the RestClient::Request class, which provides a lower-level API.`
adding :block_response parameter 2010-12-07 13:50:54 -05:00
			`You can:`

			`* specify ssl parameters`
			`* override cookies`
Copy-edit README 2013-08-04 16:34:25 -04:00			`* manually handle the response (e.g. to operate on it as a stream rather than reading it all into memory)`
adding :block_response parameter 2010-12-07 13:50:54 -05:00
Copy-edit README 2013-08-04 16:34:25 -04:00			`See RestClient::Request's documentation for more information.`
Link to Request class, so the rdoc will be usefull. 2009-12-17 15:27:40 -05:00
Rollback, still doesn't work 2009-12-26 09:51:47 -05:00			`== Shell`
README and some rdoc comments 2008-03-09 16:25:18 -04:00
expand shell docs 2008-07-20 16:13:16 -04:00			`The restclient shell command gives an IRB session with RestClient already loaded:`
Easy to use shell! 2008-07-07 22:49:10 -04:00
expand shell docs 2008-07-20 16:13:16 -04:00			`$ restclient`
Updated README to match with Response refactoring 2010-02-01 12:12:21 -05:00			`>> RestClient.get 'http://example.com'`
README and some rdoc comments 2008-03-09 16:25:18 -04:00
expand shell docs 2008-07-20 16:13:16 -04:00			`Specify a URL argument for get/post/put/delete on that resource:`
Save named settings for restclient in ~/.restclient ~/.restclient spec: name: :url: http://mydomain.com :username: myusername :password: supersecret 2008-07-16 19:15:26 -04:00
expand shell docs 2008-07-20 16:13:16 -04:00			`$ restclient http://example.com`
Updated README to match with Response refactoring 2010-02-01 12:12:21 -05:00			`>> put '/resource', 'data'`
Save named settings for restclient in ~/.restclient ~/.restclient spec: name: :url: http://mydomain.com :username: myusername :password: supersecret 2008-07-16 19:15:26 -04:00
expand shell docs 2008-07-20 16:13:16 -04:00			`Add a user and password for authenticated resources:`

			`$ restclient https://example.com user pass`
Updated README to match with Response refactoring 2010-02-01 12:12:21 -05:00			`>> delete '/private/resource'`
expand shell docs 2008-07-20 16:13:16 -04:00
			`Create ~/.restclient for named sessions:`
Save named settings for restclient in ~/.restclient ~/.restclient spec: name: :url: http://mydomain.com :username: myusername :password: supersecret 2008-07-16 19:15:26 -04:00
expand shell docs 2008-07-20 16:13:16 -04:00			`sinatra:`
use strings instead of symbols in .restclient sessions 2008-08-01 14:48:56 -04:00			`url: http://localhost:4567`
expand shell docs 2008-07-20 16:13:16 -04:00			`rack:`
use strings instead of symbols in .restclient sessions 2008-08-01 14:48:56 -04:00			`url: http://localhost:9292`
expand shell docs 2008-07-20 16:13:16 -04:00			`private_site:`
use strings instead of symbols in .restclient sessions 2008-08-01 14:48:56 -04:00			`url: http://example.com`
			`username: user`
			`password: pass`
Save named settings for restclient in ~/.restclient ~/.restclient spec: name: :url: http://mydomain.com :username: myusername :password: supersecret 2008-07-16 19:15:26 -04:00
expand shell docs 2008-07-20 16:13:16 -04:00			`Then invoke:`

			`$ restclient private_site`
Rollback, still doesn't work 2009-12-26 09:51:47 -05:00
Added back the logging documentation which has been erased by the merge 2010-01-25 12:14:05 -05:00			`Use as a one-off, curl-style:`

			`$ restclient get http://example.com/resource > output_body`

			`$ restclient put http://example.com/resource < input_body`

			`== Logging`

Copy-edit README 2013-08-04 16:34:25 -04:00			`To enable logging you can:`
Added back the logging documentation which has been erased by the merge 2010-01-25 12:14:05 -05:00
Copy-edit README 2013-08-04 16:34:25 -04:00			`* set RestClient.log with a Ruby Logger, or`
			`* set an environment variable to avoid modifying the code (in this case you can use a file name, "stdout" or "stderr"):`
Added back the logging documentation which has been erased by the merge 2010-01-25 12:14:05 -05:00
			`$ RESTCLIENT_LOG=stdout path/to/my/program`

			`Either produces logs like this:`

			`RestClient.get "http://some/resource"`
			`# => 200 OK \| text/html 250 bytes`
			`RestClient.put "http://some/resource", "payload"`
			`# => 401 Unauthorized \| application/xml 340 bytes`

			`Note that these logs are valid Ruby, so you can paste them into the restclient`
			`shell or a script to replay your sequence of rest calls.`

			`== Proxy`

			`All calls to RestClient, including Resources, will use the proxy specified by`
			`RestClient.proxy:`

			`RestClient.proxy = "http://proxy.example.com/"`
			`RestClient.get "http://some/resource"`
			`# => response from some/resource as proxied through proxy.example.com`

Copy-edit README 2013-08-04 16:34:25 -04:00			`Often the proxy URL is set in an environment variable, so you can do this to`
Added back the logging documentation which has been erased by the merge 2010-01-25 12:14:05 -05:00			`use whatever proxy the system is configured to use:`

			`RestClient.proxy = ENV['http_proxy']`

Added a section to the README on passing query parameters 2011-07-06 17:01:48 -04:00			`== Query parameters`

			`Request objects know about query parameters and will automatically add them to`
Copy-edit README 2013-08-04 16:34:25 -04:00			`the URL for GET, HEAD and DELETE requests, escaping the keys and values as needed:`
Added a section to the README on passing query parameters 2011-07-06 17:01:48 -04:00
			`RestClient.get 'http://example.com/resource', :params => {:foo => 'bar', :baz => 'qux'}`
			`# will GET http://example.com/resource?foo=bar&baz=qux`

Added back the logging documentation which has been erased by the merge 2010-01-25 12:14:05 -05:00			`== Cookies`

			`Request and Response objects know about HTTP cookies, and will automatically`
			`extract and set headers for them as needed:`

			`response = RestClient.get 'http://example.com/action_which_sets_session_id'`
			`response.cookies`
			`# => {"_applicatioN_session_id" => "1234"}`

			`response2 = RestClient.post(`
			`'http://localhost:3000/',`
			`{:param1 => "foo"},`
			`{:cookies => {:session_id => "1234"}}`
			`)`
			`# ...response body`

			`== SSL Client Certificates`

			`RestClient::Resource.new(`
			`'https://example.com',`
			`:ssl_client_cert => OpenSSL::X509::Certificate.new(File.read("cert.pem")),`
			`:ssl_client_key => OpenSSL::PKey::RSA.new(File.read("key.pem"), "passphrase, if any"),`
			`:ssl_ca_file => "ca_certificate.pem",`
			`:verify_ssl => OpenSSL::SSL::VERIFY_PEER`
			`).get`

			`Self-signed certificates can be generated with the openssl command-line tool.`

Reasonably good 2010-02-16 13:03:44 -05:00			`== Hook`

Copy-edit README 2013-08-04 16:34:25 -04:00			`RestClient.add_before_execution_proc add a Proc to be called before each execution.`
			`It's handy if you need direct access to the HTTP request.`
Reasonably good 2010-02-16 13:03:44 -05:00
			`Example:`

typo for oauth 2013-07-26 21:21:56 -04:00			`# Add oauth support using the oauth gem`
Reasonably good 2010-02-16 13:03:44 -05:00			`require 'oauth'`
			`access_token = ...`

			`RestClient.add_before_execution_proc do \|req, params\|`
			`access_token.sign! req`
			`end`

			`RestClient.get 'http://example.com'`

mention rest-client-components 2010-04-23 15:50:54 -04:00			`== More`

Copy-edit README 2013-08-04 16:34:25 -04:00			`Need caching, more advanced logging or any ability provided by Rack middleware?`
mention rest-client-components 2010-04-23 15:50:54 -04:00
Copy-edit README 2013-08-04 16:34:25 -04:00			`Have a look at rest-client-components: http://github.com/crohr/rest-client-components`
mention rest-client-components 2010-04-23 15:50:54 -04:00
Split up 'Meta' into 'Credits' and 'Legal', and update names 2013-03-21 16:14:19 -04:00			`== Credits`
README and some rdoc comments 2008-03-09 16:25:18 -04:00
Add history notes for upcoming 1.6.8 release. 2014-04-25 21:36:44 -04:00			`REST Client Team:: Matthew Manning, Lawrence Leonard Gilbert, Andy Brody`
Split up 'Meta' into 'Credits' and 'Legal', and update names 2013-03-21 16:14:19 -04:00
			`Creator:: Adam Wiggins`

			`Maintainer Emeritus:: Julien Kirch`

			`Major contributions:: Blake Mizerany, Julien Kirch`
credits update 2008-08-03 19:12:05 -04:00
Block for response done, easier than expected! 2010-01-22 15:04:49 -05:00			`Patches contributed by many, including Chris Anderson, Greg Borenstein, Ardekantur, Pedro Belo, Rafael Souza, Rick Olson, Aman Gupta, François Beausoleil and Nick Plante.`
Chris Anderson's fix to use full request uri 2008-03-20 21:29:39 -04:00
Split up 'Meta' into 'Credits' and 'Legal', and update names 2013-03-21 16:14:19 -04:00			`== Legal`

README and some rdoc comments 2008-03-09 16:25:18 -04:00			`Released under the MIT License: http://www.opensource.org/licenses/mit-license.php`
Replace master_shake.jpg with image having permissive license The new image has a Creative Commons Attribution-ShareAlike 2.0 Generic license; credits are in README 2013-03-17 16:04:37 -04:00
			`"Master Shake" photo (http://www.flickr.com/photos/solgrundy/924205581/) by`
			`"SolGrundy"; used under terms of the Creative Commons Attribution-ShareAlike 2.0`
			`Generic license (http://creativecommons.org/licenses/by-sa/2.0/)`
Add legal note about puppetlabs code to README. 2014-04-02 01:43:51 -04:00
			`Code for reading Windows root certificate store derived from work by Puppet;`
			`used under terms of the Apache License, Version 2.0.`