mirror of
https://github.com/rest-client/rest-client.git
synced 2022-11-09 13:49:40 -05:00
120 lines
3.4 KiB
Text
120 lines
3.4 KiB
Text
= 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 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'
|
|
|
|
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).
|
|
|
|
IRC: #rest-client at freenode
|
|
|
|
== 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
|