rest-core Build Status

by Cardinal Blue http://cardinalblue.com

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.

REQUIREMENTS:

  • Tested with MRI (official CRuby) 1.8.7, 1.9.2, 1.9.3, Rubinius and JRuby
  • gem rest-client (for now)

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.

Build Your Own Clients:

require 'rest-core'

YourClient = RestCore::Builder.client do
  s = self.class # this is only for ruby 1.8!
  use s::DefaultSite , 'https://api.github.com/users/'
  use s::JsonDecode  , true
  use s::CommonLogger, method(:puts)
  use s::Cache       , {}, 3600
  run s::RestClient
end

client = YourClient.new
client.get('cardinalblue') # cache miss
client.get('cardinalblue') # cache hit

client.site = 'http://github.com/api/v2/json/user/show/'
client.get('cardinalblue') # cache miss
client.get('cardinalblue') # cache hit

Please see rest-more for more complex examples, and slides from rubyconf.tw/2011 for concepts.

rest-core users:

GLOSSARY:

  • A client is a class which can new connections to make requests. For instance, RestCore::Facebook.new.get('4')

  • An app is an HTTP client which would do the underneath HTTP requests. For instance, RestCore::RestClient is an HTTP client which uses rest-client gem (::RestClient) to make HTTP requests.

  • A middleware is a component for a rest-core stack. For instance, RestCore::DefaultSite is a middleware which would add default site URL in front of the request URI if it is not started with http://, thus you can do this: RestCore::Facebook.get('4') without specifying where the site (Facebook) it is.

  • RestCore::Wrapper is a utility which could help you wrap a number of middlewares into another middleware. Currently, it's used in RestCore::Buidler and RestCore::Cache.

  • RestCore::Builder is a utility which could help you build a client with a collection of middlewares and an app. i.e. a rest-core stack.

  • RestCore::Middleware is a utility which could help you build a non-trivial middleware. More explanation to come...

  • RestCore::Client is a module which would be included in a generated client by RestCore::Builder. It contains a number of convenient functions which is generally useful.

  • RestCore::ClientOAuth1 is a module which should be included in a OAuth1.0 client. It contains a number of convenient functions which is useful for an OAuth 1.0 client.

  • An env is a hash which contains all the information for both request and response. It's mostly seen in @app.call(env) See other explanation such as env[RestCore::REQUEST_METHOD] for more detail.

  • env[RestCore::REQUEST_METHOD] is a symbol representing which HTTP method would be used in the subsequent HTTP request. The possible values are either: :get, :post, :put or :delete.

  • env[RestCore::REQUEST_PATH] is a string representing which HTTP path would be used in the subsequent HTTP request. This path could also include the protocol, not only the path. e.g. "http://graph.facebook.com/4" or simply "4". In the case of built-in Facebook client, the RestCore::DefaultSite middleware would take care of the site.

  • env[RestCore::REQUEST_QUERY] is a hash which keys are query keys and values are query values. Both keys and values' type should be String, not Symbol. Values with nil or false would be ignored. Both keys and values would be escaped automatically.

  • env[RestCore::REQUEST_PAYLOAD] is a hash which keys are payload keys and values are payload values. Both keys and values' type should be String, not Symbol. Values with nil or false would be ignored. Both keys and values would be escaped automatically.

  • env[RestCore::REQUEST_HEADERS] is a hash which keys are header names and values are header values. Both keys and values' type should be String, not Symbol. Values with nil or false would be ignored.

  • env[RestCore::RESPONSE_BODY] is a string which is returned by the server. Might be nil if there's no response or not yet making HTTP request.

  • env[RestCore::RESPONSE_STATUS] is a number which is returned by the server for the HTTP status. Might be nil if there's no response or not yet making HTTP request.

  • env[RestCore::RESPONSE_HEADERS] is a hash which is returned by the server for the response headers. Both keys and values' type should be String.

  • env[RestCore::DRY] is a boolean (either true or false or nil) which indicates that if we're only asking for modified env, instead of making real requests. It's used to ask for the real request URI, etc.

  • env[RestCore::FAIL] is an array which contains failing events. Events could be any objects, it's handled by RestCore::ErrorDetector or any other custom middleware.

  • env[RestCore::LOG] is an array which contains logging events. Events could be any objects, it's handled by RestCore::CommonLogger or any other custom middleware.

CONTRIBUTORS:

  • Andrew Liu (@eggegg)
  • andy (@coopsite)
  • Barnabas Debreczeni (@keo)
  • Bruce Chu (@bruchu)
  • Ethan Czahor (@ethanz5)
  • Florent Vaucelle (@florent)
  • Jaime Cham (@jcham)
  • John Fan (@johnfan)
  • Lin Jen-Shin (@godfat)
  • Mariusz Pruszynski (@snicky)
  • Mr. Big Cat (@miaout17)
  • Nicolas Fouché (@nfo)

LICENSE:

Apache License 2.0

Copyright (c) 2011, Cardinal Blue

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.