From bab348bc524d2a13b342008f16b27c0ed4f1bed4 Mon Sep 17 00:00:00 2001 From: Andy Brody Date: Mon, 22 Aug 2016 17:50:06 -0400 Subject: [PATCH 1/2] Improve some of the example docs slightly. --- README.md | 44 +++++++++++++++++++++++++++++++------------- 1 file changed, 31 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 24efc4f..b189dee 100644 --- a/README.md +++ b/README.md @@ -75,30 +75,48 @@ Overview of significant changes: See [history.md](./history.md) for a more complete description of changes. ## Usage: Raw URL + +Basic usage: + +```ruby +require 'rest-client' + +RestClient.get(url, headers={}) + +RestClient.post(url, payload, headers={}) +``` + +In the high level helpers, only POST, PATCH, and PUT take a payload argument. +To pass a payload with other HTTP verbs or to pass more advanced options, use +`RestClient::Request.execute` instead. + +More detailed examples: + ```ruby require 'rest-client' RestClient.get 'http://example.com/resource' -RestClient.get 'http://example.com/resource', {:params => {:id => 50, 'foo' => 'bar'}} +RestClient.get 'http://example.com/resource', {params: {id: 50, 'foo' => 'bar'}} -RestClient.get 'https://user:password@example.com/private/resource', {:accept => :json} +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', {param1: 'one', nested: {param2: 'two'}} -RestClient.post "http://example.com/resource", { 'x' => 1 }.to_json, :content_type => :json, :accept => :json +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\n\n> 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.body +=> "\n\n\n Example Domain\n\n ..." RestClient.post( url, { From 25b3c117ea44319d93b5cc58d449b563bbee8efc Mon Sep 17 00:00:00 2001 From: Andy Brody Date: Sat, 10 Sep 2016 11:51:17 -0400 Subject: [PATCH 2/2] Improve documentation around exception handling. --- README.md | 41 ++++++++++++++++++++++++++++++++--------- 1 file changed, 32 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index b189dee..67deb63 100644 --- a/README.md +++ b/README.md @@ -209,21 +209,44 @@ See `RestClient::Resource` docs for details. - 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 +- for other cases, a `RestClient::ExceptionWithResponse` holding the Response will be raised; a specific exception class will be thrown for known error codes - call `.response` on the exception to get the server's response ```ruby -RestClient.get 'http://example.com/resource' -➔ RestClient::ResourceNotFound: RestClient::ResourceNotFound +>> RestClient.get 'http://example.com/nonexistent' +Exception: RestClient::NotFound: 404 Not Found -begin - RestClient.get 'http://example.com/resource' -rescue => e - e.response -end -➔ 404 Resource Not Found | text/html 282 bytes +>> begin + RestClient.get 'http://example.com/nonexistent' + rescue RestClient::ExceptionWithResponse => e + e.response + end +=> ``` +### Other exceptions + +While most exceptions have been collected under `RestClient::RequestFailed` aka +`RestClient::ExceptionWithResponse`, there are a few quirky exceptions that +have been kept for backwards compatibility. + +RestClient will propagate up exceptions like socket errors without modification: + +```ruby +>> RestClient.get 'http://localhost:12345' +Exception: Errno::ECONNREFUSED: Connection refused - connect(2) for "localhost" port 12345 +``` + +RestClient handles a few specific error cases separately in order to give +better error messages. These will hopefully be cleaned up in a future major +release. + +`RestClient::ServerBrokeConnection` is translated from `EOFError` to give a +better error message. + +`RestClient::SSLCertificateNotVerified` is raised when HTTPS validation fails. +Other `OpenSSL::SSL::SSLError` errors are raised as is. + ### Redirection By default, rest-client will follow HTTP 30x redirection requests.