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