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 - https://github.com/adamwiggins/rest-client
- curb - https://github.com/taf2/curb
- patron - https://github.com/toland/patron
And again, the Github crew for this amazing service!