rest-client-components¶ ↑

RestClient on steroids !

Want to add transparent HTTP caching to the rest-client gem ? It’s as simple as:

require 'restclient/components'
require 'rack/cache'
RestClient.enable Rack::Cache
RestClient.get "http://some/cacheable/resource"

Want to log the requests in the commonlog format ?

require 'restclient/components'
RestClient.enable Rack::CommonLogger, STDOUT
RestClient.get "http://some/resource"

Want to enable both ?

require 'restclient/components'
require 'rack/cache'
RestClient.enable Rack::CommonLogger, STDOUT
RestClient.enable Rack::Cache
RestClient.get "http://some/cacheable/resource"

This works with any Rack middleware, thus you can reuse the wide range of existing Rack middleware to add functionalities to RestClient with very little effort. The order in which you enable components will be respected.

Note that the rest-client behaviour is also respected: you’ll get back a RestClient::Response or RestClient exceptions as a result of your requests. If you prefer a more rack-esque approach, just disable the Compatibility component, and you will get back a response conform to the Rack SPEC:

require 'restclient/components'
RestClient.disable RestClient::Rack::Compatibility
status, header, body = RestClient.get('http://some/url')

In that case, you will only get exceptions for connection or timeout errors (RestClient::ServerBrokeConnection or RestClient::RequestTimeout)

See the examples folder for more details.

Installation¶ ↑

gem install rest-client-components
gem install rack-cache # if you want to use Rack::Cache

Usage¶ ↑

Example with Rack::Cache, and Rack::CommonLogger

require 'restclient/components'
require 'rack/cache'

RestClient.enable Rack::CommonLogger
# Enable the cache Rack middleware, and store both meta and entity data in files:
# See http://rtomayko.github.io/rack-cache/configuration for the list of available options
RestClient.enable Rack::Cache, 
                  :metastore => 'file:/tmp/cache/meta', 
                  :entitystore => 'file:/tmp/cache/body'

# ... done !
# Then you can make your requests as usual: 
# You'll get a log for each call, and the resources will be automatically and transparently cached for you according to their HTTP headers.
# Cache invalidation on requests other than GET is also transparently supported, thanks to Rack::Cache. Enjoy !

RestClient.get 'http://some/cacheable/resource'
# or
resource = RestClient::Resource.new('http://some/cacheable/resource')

# obviously, caching is only interesting if you request the same resource multiple times, e.g. :
resource.get # get from origin server, and cache if possible
resource.get # get from cache, if still fresh.
resource.put(...) # will automatically invalidate the cache, so that a subsequent GET request on the same resource does not return the cached resource
resource.get # get from origin server, and cache if possible
# ...
resource.get(:cache_control => 'no-cache') # explicitly tells to bypass the cache, requires rack-cache >= 0.5 and :allow_reload => true option
# ...
resource.delete(...) # will invalidate the cache
resource.get # should raise a RestClient::ResourceNotFound exception

Now, you just need to make your resources cacheable, so unless you’ve already taken care of that, do yourself a favor and read:

• the HTTP specification related to HTTP caching - www.w3.org/Protocols/rfc2616/rfc2616-sec13.html

• Things Caches Do - tomayko.com/writings/things-caches-do

Dependencies¶ ↑

• rest-client >= 1.4.1

• rack >= 1.0.1

COPYRIGHT¶ ↑

Copyright © 2009-2010 Cyril Rohr. See LICENSE for details.