A streaming REST client for Ruby that uses libcurl
Features
-
rest-client like API
-
Streaming API allows the caller to be handed chunks of the response while it’s being received
-
uses Encoding.default_internal (otherwise falls back to utf-8) for strings it hands back in 1.9
How to install
Nothing special about it, just:
sudo gem install streamly
Example of use
A basic HEAD request
Streamly.head 'www.somehost.com'
Or streaming
Streamly.head 'www.somehost.com' do |header_chunk|
# do something with header_chunk
end
You can also pass a Hash of headers
Streamly.head 'www.somehost.com', {"User-Agent" => "Your Mom"}
A basic GET request
Streamly.get 'www.somehost.com'
Or streaming
Streamly.get 'www.somehost.com' do |body_chunk|
# do something with body_chunk
end
You can also pass a Hash of headers
Streamly.get 'www.somehost.com', {"User-Agent" => "Your Mom"}
A basic POST request
Streamly.post 'www.somehost.com', 'blah=foo'
Or streaming
Streamly.post 'www.somehost.com', 'blah=foo' do |body_chunk|
# do something with body_chunk
end
You can also pass a Hash of headers
Streamly.post 'www.somehost.com', 'blah=foo', {"User-Agent" => "Your Mom"}
A basic PUT request
Streamly.put 'www.somehost.com', 'blah=foo'
Or streaming
Streamly.put 'www.somehost.com', 'blah=foo' do |body_chunk|
# do something with body_chunk
end
You can also pass a Hash of headers
Streamly.put 'www.somehost.com', 'blah=foo', {"User-Agent" => "Your Mom"}
A basic DELETE request
Streamly.delete 'www.somehost.com'
Or streaming
Streamly.delete 'www.somehost.com' do |body_chunk|
# do something with body_chunk
end
You can also pass a Hash of headers
Streamly.delete 'www.somehost.com', {"User-Agent" => "Your Mom"}
Benchmarks
Fetching 2,405,005 bytes of JSON from a local lighttpd server
-
Streamly: 0.011s
-
Shell out to curl: 0.046s
-
rest-client: 0.205s
Streaming, and parsing 2,405,005 bytes of JSON from a local lighttpd server
-
Streamly: 0.231s
-
Shell out to curl: 0.341s
-
rest-client: 0.447s
Other Notes
This library was basically an exercise in dealing with libcurl in C.
Special Thanks
There are quite a few extremely nice REST client libraries out there for Ruby today. I especially owe thanks to the following projects. Without them I probably would have never had the inspiration to even take the time to write this library. In Streamly, you’ll find snippets of code, API patterns and examples from all 3 of these projects. I’ll do my best to make sure I give credit where it’s due in the source. Please let me know if I’ve missed something!
-
rest-client - github.com/adamwiggins/rest-client
-
curb - github.com/taf2/curb
-
patron - github.com/toland/patron
And again, the Github crew for this amazing service!