README.rdoc in rest-client-1.2.0 vs README.rdoc in rest-client-1.3.0
- old
+ new
@@ -1,8 +1,8 @@
-= REST Client -- simple DSL for accessing REST resources
+= REST Client -- simple DSL for accessing HTTP and REST resources
-A simple REST client for Ruby, inspired by the Sinatra's microframework style
+A simple HTTP and REST client for Ruby, inspired by the Sinatra's microframework style
of specifying actions: get, put, post, delete.
== Usage: Raw URL
require 'rest_client'
@@ -47,30 +47,75 @@
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
+
+* for results code between 200 and 206 a RestClient::Response will be returned
+* for results code between 301 and 303 the redirection will be automatically followed
+* for other result codes a RestClient::Exception holding the Response will be raised, a specific exception class will be thrown for know error codes
+
+ RestClient.get 'http://example.com/resource'
+ ➔ RestClient::ResourceNotFound: RestClient::ResourceNotFound
+
+ begin
+ RestClient.get 'http://example.com/resource'
+ rescue => e
+ e.response
+ end
+ ➔ "<!DOCTYPE HTML PUBLIC \"-//IETF//DTD HTML 2.0//EN\">\n<html><head>\n<title>404 Not Found</title>..."
+
+== 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 (return the Response for 200..206, raise an exception in other cases).
+
+ # Don't raise exceptions but return the response
+ RestClient.get('http://example.com/resource'){|response| response}
+ ➔ "<!DOCTYPE HTML PUBLIC \"-//IETF//DTD HTML 2.0//EN\">\n<html><head>\n<title>404 Not Found</title>..."
+
+ # Manage a specific error code
+ RestClient.get('http://my-rest-service.com/resource'){ |response|
+ case response.code
+ when 200
+ p "It worked !"
+ response
+ when 423
+ raise SomeCustomExceptionIfYouWant
+ else
+ response.return!
+ end
+ }
+
+== Non-normalized URIs.
+
+If you want to use non-normalized URIs, you can normalize them with the addressable gem (http://addressable.rubyforge.org/api/).
+
+ 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::Resource 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'
+ ➔ RestClient.get 'http://example.com'
Specify a URL argument for get/post/put/delete on that resource:
$ restclient http://example.com
- >> put '/resource', 'data'
+ ➔ put '/resource', 'data'
Add a user and password for authenticated resources:
$ restclient https://example.com user pass
- >> delete '/private/resource'
+ ➔ delete '/private/resource'
Create ~/.restclient for named sessions:
sinatra:
url: http://localhost:4567
@@ -83,14 +128,81 @@
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']
+
+== 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.
+
== Meta
-Written by Adam Wiggins, major modifications by Blake Mizerany, maintained by Archiloque
+Written by Adam Wiggins, major modifications by Blake Mizerany, maintained by Julien Kirch
-Patches contributed by: Chris Anderson, Greg Borenstein, Ardekantur, Pedro Belo, Rafael Souza, Rick Olson, Aman Gupta, François Beausoleil and Nick Plante.
+Patches contributed by many, including 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
Main page: http://github.com/archiloque/rest-client