# rest-core <https://github.com/cardinalblue/rest-core>
by Cardinal Blue <http://cardinalblue.com>
Lin Jen-Shin ([godfat]) had given a talk about rest-core on
[RubyConf Taiwan 2011]. The slide is in English, but the
talk is in Mandarin.
You can also read some other topics at [doc]
[godfat]: https://github.com/godfat
[RubyConf Taiwan 2011]: http://rubyconf.tw/2011/#6
[doc]: https://github.com/cardinalblue/rest-core/blob/master/doc/ToC.md
## DESCRIPTION:
Modular Ruby clients interface for REST APIs
There has been an explosion in the number of REST APIs available
today.
To address the need for a way to access these APIs easily and
elegantly,
we have developed [rest-core], which consists of composable middleware
that allows you to build a REST client for any REST API. Or in the
case of
common APIs such as Facebook, Github, and Twitter, you can simply use
the
dedicated clients provided by [rest-more].
[rest-core]: https://github.com/cardinalblue/rest-core
[rest-more]: https://github.com/cardinalblue/rest-more
## INSTALLATION:
gem install rest-core
Or if you want development version, put this in Gemfile:
gem 'rest-core', :git => 'git://github.com/cardinalblue/rest-
core.git',
:submodules => true
If you just want to use Facebook or Twitter clients, please take a
look at
[rest-more] which has a lot of clients built with rest-core.
## CHANGES:
### rest-core 1.0.0 -- 2012-03-17
This is a very significant release. The most important change is now
we
support asynchronous requests, by either passing a callback block or
using
fibers in Ruby 1.9 to make the whole program still look synchronous.
Please read [README.md](https://github.com/cardinalblue/rest-core/blob/
master/README.md)
or [example](https://github.com/cardinalblue/rest-core/tree/master/
example)
for more detail.
* [`Client`] Client#inspect is fixed for clients which do not have any
attributes.
* [`Client`] HEAD, OPTIONS, and PATCH requests are added. For example:
client = Client.new
client.head('path')
client.options('path')
client.patch('path')
* [`Client`] Now if you passed a block to either `get` or `post` or
other
requests, the response would be returned to the block instead the
caller.
In this case, the return value of `get` or `post` would be the
client
itself. For example:
client = Client.new
client.get('path'){ |response| puts response.insepct }.
get('math'){ |response| puts response.insepct }
* [`RestClient`] Now all the response headers names are converted to
upper
cases and underscores (_). Also, if a header has only presented
once, it
would not be wrapped inside an array. This is more consistent with
em-http-request, cool.io-http, and http_parser.rb
* [`RestClient`] From now on, the default HTTP client, i.e.
`RestClient` won't
follow any redirect. To follow redirect, please use `FollowRedirect`
middleware. Two reasons. One is that the underlying HTTP client
should
be minimal. Another one is that a FollowRedirect middleware could be
used for all HTTP clients. This would make it more consistent across
all HTTP clients.
* [`RestClient`] Added a patch to avoid `"123".to_i` returning `200`,
please see: <https://github.com/archiloque/rest-client/pull/103>
I would remove this once after this patch is merged.
* [`RestClient`] Added a patch to properly returning response whenever
a redirect is happened. Please see:
<https://github.com/archiloque/rest-client/pull/118>
I would remove this once after this patch is merged.
* [`FollowRedirect`] This middleware would follow the redirect. Pass
:max_redirects for the maximum redirect times. For example:
Client = RestCore::Builder.client do
use FollowRedirect, 2 # default :max_redirects
end
client = Client.new
client.get('path', {}, :max_redirects => 5)
* [`Middleware`] Added `Middleware#run` which can return the
underlying HTTP
client, if you need to know the underlying HTTP client can support
asynchronous requests or not.
* [`Cache`] Now it's asynchrony-aware.
* [`CommonLogger`] Now it's asynchrony-aware.
* [`ErrorDetector`] Now it's asynchrony-aware.
* [`ErrorHandler`] Now it's asynchrony-aware.
* [`JsonDecode`] Now it's asynchrony-aware.
* [`Timeout`] Now it's asynchrony-aware.
* [`Universal`] `FollowRedirect` middleware is added.
* [`Universal`] `Defaults` middleware is removed.
* Added `RestCore::ASYNC` which should be the callback function which
is
called whenever the response is available. It's similar to Rack's
async.callback.
* Added `RestCore::TIMER` which is only used in Timeout middleware. We
need
this to disable timer whenever the response is back.
* [`EmHttpRequestAsync`] This HTTP client accepts a block to make
asynchronous
HTTP requests via em-http-request gem.
* [`EmHttpRequestFiber`] This HTTP client would make asynchronous HTTP
requests with em-http-request but also wrapped inside a fiber, so
that it
looks synchronous to the program who calls it.
* [`EmHttpRequest`] This HTTP client would would use
`EmHttpRequestAsync` if
a block (`RestCore::ASYNC`) is passed, otherwise use
`EmHttpRequestFiber`.
* [`CoolioAsync`] This HTTP client is basically the same as
`EmHttpRequestAsync`, but using cool.io-http instead of em-http-
request.
* [`CoolioFiber`] This HTTP client is basically the same as
`EmHttpRequestFiber`, but using cool.io-http instead of em-http-
request.
* [`Coolio`] This HTTP client is basically the same as
`EmHttpRequest`,
but using cool.io-http instead of em-http-request.
* [`Auto`] This HTTP client would auto-select a suitable client. Under
eventmachine, it would use `EmHttpRequest`. Under cool.io, it would
use
`Coolio`. Otherwise, it would use `RestClient`.