The fourth release candidate for rest-client 2.0.0 is now available
for testing from GitHub and RubyGems.org.
The 2.0.0 major release is largely API compatible with the 1.x series,
but it makes several major changes and represents a large amount of work
by many different contributors. Please file any bugs at
If there are no major bugs, this should be the last release candidate
before a final 2.0.0 release.
Most notable changes:
- This release drops support for Ruby 1.9 and below, which was necessary
to support mime-types 3.x.
- Response handling has been refactored for clarity.
RestClient::Response objects are now a subclass of String rather than
a String object with response functionality mixed in. This makes it
much more obvious what type of object you're working with, and avoids
many gotchas and bugs around object serialization and other surprises.
Call .to_s or .body on response objects to get a plain String object.
- Responses now respect Content-Type charset headers. A valid charset
header will result in a response with an appropriate string encoding.
For example, `Content-Type: text/plain; charset=EUC-JP` will result in
a body String encoded with `Encoding::EUC_JP`.
- Cookie processing has been completely rewritten to use cookie jars.
The `:cookies` option to RestClient::Request now accepts HTTP::CookieJar
objects in initialization. The prior API still works, but will put the
cookies in a cookie jar under the hood. This cookie jar is also used for
responses and redirection, allowing for browser-like handling of cookies
throughout. Request and Response objects now expose a `#cookie_jar`,
which is recommended for use instead of `#cookies`.
- The exceptions raised on timeouts have changed. Instead of
RestClient::RequestTimeout (which is still used for HTTP 408 "Request
Timeout"), network timeouts will now raise either
RestClient::Exceptions::OpenTimeout, both of which inherit from
RestClient::Exceptions::Timeout. This class also makes the original
wrapped exception available as `#original_exception`.
- Redirect handling has been improved in a few ways:
1. RestClient::MaxRedirectsReached has been removed in favor of the
normal rest-client HTTP response exceptions. These exceptions expose
the response object with `#response`, making it now possible to handle
these responses normally.
2. Response objects now have a `#history` method that exposes a list
of prior responses from an HTTP redirection chain. Previously it was
not possible to know what earlier responses were encountered after
3. It is now much easier to manually follow redirection, by setting
`max_redirects: 0`, catching the ExceptionWithResponse, and calling
- HTTP params processing for GET and POST requests refactored:
There is new, more sophisticated code for handling GET/POST params
passed as a structured hash. Both GET and POST now use common code in
RestClient::Utils: `.encode_query_string` and `.flatten_params`. You can
now pass deeply nested hashes and arrays, empty values, even null, and
rest-client will try very hard to render the params in a way that will
be intelligible to Rack or PHP based servers. (There is no standard
defining this behavior, so we had to ad lib.) You can also use the new
RestClient::ParamsArray class to pass multiple keys with the same name
or where the ordering is significant.
There were also various bugs squashed and enhancements added:
- IPv6 address support was corrected in various places.
- Multiple HTTP response headers with the same name are now joined per
- HTTP proxies can now be configured or disabled on a per-request basis.
- before_execution_procs can now be added on a per-request basis.
- Streaming request payloads will now require dramatically less memory.
- A useful User-Agent header is now added identifying the agent as
rest-client by version.
- Several gotchas and more complicated rest-client use cases are now
documented in the README.
Please see https://github.com/rest-client/rest-client/blob/v2.0.0.rc4/history.md
for a complete list of changes.