Skip to content
Newer
Older
100644 339 lines (251 sloc) 11.3 KB
440ab57 @godfat README.md: show build status about master branch; show powered sites
godfat authored
1 # rest-core [![Build Status](https://secure.travis-ci.org/godfat/rest-core.png?branch=master)](http://travis-ci.org/godfat/rest-core)
bc33051 @godfat an extra blankline
godfat authored
2
1a9919e @godfat update Rakefile accordingly, add a stub of README.md, add version file
godfat authored
3 by Cardinal Blue <http://cardinalblue.com>
4
fd06e53 @godfat README.md: break lines
godfat authored
5 Lin Jen-Shin ([godfat][]) had given a talk about rest-core on
6 [RubyConf Taiwan 2011][talk]. The slide is in English, but the
7 talk is in Mandarin.
eb7de1b @godfat README.md: show the talk
godfat authored
8
36c1991 @godfat README.md: fix ToC link
godfat authored
9 You can also read some other topics at [doc](https://github.com/cardinalblue/rest-core/blob/master/doc/ToC.md).
a87d0c4 @godfat README.md: small tweak
godfat authored
10
eb7de1b @godfat README.md: show the talk
godfat authored
11 [godfat]: https://github.com/godfat
12 [talk]: http://rubyconf.tw/2011/#6
13
1a9919e @godfat update Rakefile accordingly, add a stub of README.md, add version file
godfat authored
14 ## LINKS:
15
1dc6f63 @godfat fix github url
godfat authored
16 * [github](https://github.com/cardinalblue/rest-core)
dba4324 @godfat README.md: fix link
godfat authored
17 * [rubygems](https://rubygems.org/gems/rest-core)
1a9919e @godfat update Rakefile accordingly, add a stub of README.md, add version file
godfat authored
18 * [rdoc](http://rdoc.info/projects/cardinalblue/rest-core)
19 * [mailing list](http://groups.google.com/group/rest-core/topics)
20
d4b637b @godfat move long description to NOTE.md
godfat authored
21 ## DESCRIPTION:
22
2d8f516 @godfat prepare release and update CHANGES and README
godfat authored
23 Modular Ruby clients interface for REST APIs
64f71bd @godfat README.md: add travis image and update requirement
godfat authored
24
024d11c @godfat update description, bump gemspec and version
godfat authored
25 There has been an explosion in the number of REST APIs available today.
26 To address the need for a way to access these APIs easily and elegantly,
27 we have developed [rest-core][], which consists of composable middleware
28 that allows you to build a REST client for any REST API. Or in the case of
29 common APIs such as Facebook, Github, and Twitter, you can simply use the
2d8f516 @godfat prepare release and update CHANGES and README
godfat authored
30 dedicated clients provided by [rest-more][].
965793b @godfat README.md: update DESCRIPTION
godfat authored
31
a87d0c4 @godfat README.md: small tweak
godfat authored
32 [rest-core]: https://github.com/cardinalblue/rest-core
33 [rest-more]: https://github.com/cardinalblue/rest-more
34
35 ## FEATURES:
36
37 * Modular interface for REST clients similar to WSGI/Rack for servers.
38 * Asynchronous/Synchronous styles with or without fibers are both supported.
64f71bd @godfat README.md: add travis image and update requirement
godfat authored
39
1a9919e @godfat update Rakefile accordingly, add a stub of README.md, add version file
godfat authored
40 ## REQUIREMENTS:
41
a87d0c4 @godfat README.md: small tweak
godfat authored
42 ### Mandatory:
43
44 * MRI (official CRuby) 1.8.7, 1.9.2, 1.9.3, Rubinius 1.8/1.9 and JRuby 1.8/1.9
43766b3 @godfat README.md: greatly updated
godfat authored
45 * gem rest-client
1a9919e @godfat update Rakefile accordingly, add a stub of README.md, add version file
godfat authored
46
a87d0c4 @godfat README.md: small tweak
godfat authored
47 ### Optional:
48
43766b3 @godfat README.md: greatly updated
godfat authored
49 * Fibers only work on Ruby 1.9+
50 * gem [em-http-request][] (if using eventmachine)
51 * gem [cool.io-http][] (if using cool.io)
943c8e6 @godfat README.md: small tweak
godfat authored
52 * gem json or yajl-ruby (if using `JsonDecode` middleware)
a87d0c4 @godfat README.md: small tweak
godfat authored
53
54 [em-http-request]: https://github.com/igrigorik/em-http-request
55 [cool.io-http]: https://github.com/godfat/cool.io-http
56
1a9919e @godfat update Rakefile accordingly, add a stub of README.md, add version file
godfat authored
57 ## INSTALLATION:
58
943c8e6 @godfat README.md: small tweak
godfat authored
59 ``` shell
1a9919e @godfat update Rakefile accordingly, add a stub of README.md, add version file
godfat authored
60 gem install rest-core
943c8e6 @godfat README.md: small tweak
godfat authored
61 ```
1a9919e @godfat update Rakefile accordingly, add a stub of README.md, add version file
godfat authored
62
63 Or if you want development version, put this in Gemfile:
64
848b328 @godfat README.md: this is actually ruby code in Gemfile
godfat authored
65 ``` ruby
16621f4 @godfat README.md: we need git submodule
godfat authored
66 gem 'rest-core', :git => 'git://github.com/cardinalblue/rest-core.git',
67 :submodules => true
848b328 @godfat README.md: this is actually ruby code in Gemfile
godfat authored
68 ```
1a9919e @godfat update Rakefile accordingly, add a stub of README.md, add version file
godfat authored
69
2d8f516 @godfat prepare release and update CHANGES and README
godfat authored
70 If you just want to use Facebook or Twitter clients, please take a look at
71 [rest-more][] which has a lot of clients built with rest-core.
72
73 [rest-more]: http://github.com/cardinalblue/rest-more
74
9c02343 @godfat README.md: minor edit
godfat authored
75 ## Build Your Own Clients:
1a9919e @godfat update Rakefile accordingly, add a stub of README.md, add version file
godfat authored
76
43766b3 @godfat README.md: greatly updated
godfat authored
77 You can use `RestCore::Builder` to build your own dedicated client:
78
c024ae6 @godfat ruby syntax highlighting for github
godfat authored
79 ``` ruby
fe198ad @godfat README.md: make the example more complete
godfat authored
80 require 'rest-core'
81
cea0591 @godfat README.md: fix example
godfat authored
82 YourClient = RestCore::Builder.client do
1efd726 @godfat so in the end, 1.9.3 needs that as well!
godfat authored
83 s = RestCore
fb372c0 @godfat README.md: the example in README should also work for ruby 1.8 :(
godfat authored
84 use s::DefaultSite , 'https://api.github.com/users/'
85 use s::JsonDecode , true
86 use s::CommonLogger, method(:puts)
43766b3 @godfat README.md: greatly updated
godfat authored
87 use s::Cache , nil, 3600
88 run s::RestClient # the simplest and easier HTTP client
1a9919e @godfat update Rakefile accordingly, add a stub of README.md, add version file
godfat authored
89 end
c024ae6 @godfat ruby syntax highlighting for github
godfat authored
90 ```
1a9919e @godfat update Rakefile accordingly, add a stub of README.md, add version file
godfat authored
91
43766b3 @godfat README.md: greatly updated
godfat authored
92 And use it with per-instance basis (clients could have different
93 configuration, e.g. different cache time or timeout time):
94
c024ae6 @godfat ruby syntax highlighting for github
godfat authored
95 ``` ruby
43766b3 @godfat README.md: greatly updated
godfat authored
96 client = YourClient.new(:cache => {})
d0fb273 @godfat README.md: ditto
godfat authored
97 client.get('cardinalblue') # cache miss
98 client.get('cardinalblue') # cache hit
13533d6 @godfat README.md: update SYNOPSIS
godfat authored
99
100 client.site = 'http://github.com/api/v2/json/user/show/'
d0fb273 @godfat README.md: ditto
godfat authored
101 client.get('cardinalblue') # cache miss
102 client.get('cardinalblue') # cache hit
c024ae6 @godfat ruby syntax highlighting for github
godfat authored
103 ```
1a9919e @godfat update Rakefile accordingly, add a stub of README.md, add version file
godfat authored
104
43766b3 @godfat README.md: greatly updated
godfat authored
105 Runnable example is here: [example/rest-client.rb][]. Please see [rest-more][]
106 for more complex examples, and [slides][] from [rubyconf.tw/2011][rubyconf.tw]
107 for concepts.
85394cd @godfat README.md: change SYNOPSIS to EXAMPLE; point where to find more example
godfat authored
108
43766b3 @godfat README.md: greatly updated
godfat authored
109 [example/rest-client.rb]: https://github.com/cardinalblue/rest-core/blob/master/example/rest-client.rb
02575cf @godfat extracting prebuilt clients into rest-more
godfat authored
110 [rest-more]: https://github.com/cardinalblue/rest-more
43c17d8 @godfat README.md: adding a link to the slides
godfat authored
111 [slides]: http://www.godfat.org/slide/2011-08-27-rest-core.html
ab3dbfb @godfat README.md: correct link order
godfat authored
112 [rubyconf.tw]: http://rubyconf.tw/2011/#6
85394cd @godfat README.md: change SYNOPSIS to EXAMPLE; point where to find more example
godfat authored
113
43766b3 @godfat README.md: greatly updated
godfat authored
114 ## Asynchronous HTTP Requests:
115
116 I/O bound operations shouldn't be blocking the CPU! If you have a reactor,
117 i.e. event loop, you should take the advantage of that to make HTTP requests
a47fe4d @godfat README.md: fix my english grammar...
godfat authored
118 not block the whole process/thread. For now, we support eventmachine and
43766b3 @godfat README.md: greatly updated
godfat authored
119 cool.io. Below is an example for eventmachine:
120
c024ae6 @godfat ruby syntax highlighting for github
godfat authored
121 ``` ruby
43766b3 @godfat README.md: greatly updated
godfat authored
122 require 'rest-core'
123
124 AsynchronousClient = RestCore::Builder.client do
1efd726 @godfat so in the end, 1.9.3 needs that as well!
godfat authored
125 s = RestCore
43766b3 @godfat README.md: greatly updated
godfat authored
126 use s::DefaultSite , 'https://api.github.com/users/'
127 use s::JsonDecode , true
128 use s::CommonLogger, method(:puts)
129 use s::Cache , nil, 3600
130 run s::EmHttpRequest
131 end
c024ae6 @godfat ruby syntax highlighting for github
godfat authored
132 ```
43766b3 @godfat README.md: greatly updated
godfat authored
133
134 If you're passing a block, the block is called after the response is
135 available. That is the block is the callback for the request.
136
c024ae6 @godfat ruby syntax highlighting for github
godfat authored
137 ``` ruby
27b2d00 @godfat try to make the examples more clear for non-blocking calls
godfat authored
138 client = AsynchronousClient.new
43766b3 @godfat README.md: greatly updated
godfat authored
139 EM.run{
140 client.get('cardinalblue'){ |response|
141 p response
142 EM.stop
143 }
27b2d00 @godfat try to make the examples more clear for non-blocking calls
godfat authored
144 puts "It's not blocking..."
43766b3 @godfat README.md: greatly updated
godfat authored
145 }
c024ae6 @godfat ruby syntax highlighting for github
godfat authored
146 ```
43766b3 @godfat README.md: greatly updated
godfat authored
147
148 Otherwise, if you don't pass a block as the callback, EmHttpRequest (i.e.
149 the HTTP client for eventmachine) would call `Fiber.yield` to yield to the
150 original fiber, making asynchronous HTTP requests look like synchronous.
151 If you don't understand what does this mean, you can take a look at
152 [em-synchrony][]. It's basically the same idea.
153
c024ae6 @godfat ruby syntax highlighting for github
godfat authored
154 ``` ruby
43766b3 @godfat README.md: greatly updated
godfat authored
155 EM.run{
156 Fiber.new{
157 p client.get('cardinalblue')
158 EM.stop
159 }.resume
27b2d00 @godfat try to make the examples more clear for non-blocking calls
godfat authored
160 puts "It's not blocking..."
43766b3 @godfat README.md: greatly updated
godfat authored
161 }
c024ae6 @godfat ruby syntax highlighting for github
godfat authored
162 ```
43766b3 @godfat README.md: greatly updated
godfat authored
163
164 [em-synchrony]: https://github.com/igrigorik/em-synchrony
165
166 Runnable example is here: [example/eventmachine.rb][].
167 You can also make multi-requests synchronously like this:
168
c024ae6 @godfat ruby syntax highlighting for github
godfat authored
169 ``` ruby
43766b3 @godfat README.md: greatly updated
godfat authored
170 EM.run{
171 Fiber.new{
172 fiber = Fiber.current
173 result = {}
174 client.get('cardinalblue'){ |response|
175 result[0] = response
176 fiber.resume(result) if result.size == 2
177 }
178 client.get('cardinalblue'){ |response|
179 result[1] = response
180 fiber.resume(result) if result.size == 2
181 }
182 p Fiber.yield
183 EM.stop
184 }.resume
27b2d00 @godfat try to make the examples more clear for non-blocking calls
godfat authored
185 puts "It's not blocking..."
43766b3 @godfat README.md: greatly updated
godfat authored
186 }
c024ae6 @godfat ruby syntax highlighting for github
godfat authored
187 ```
43766b3 @godfat README.md: greatly updated
godfat authored
188
189 Runnable example is here: [example/multi.rb][].
190
191 [example/eventmachine.rb]: https://github.com/cardinalblue/rest-core/blob/master/example/eventmachine.rb
192 [example/multi.rb]: https://github.com/cardinalblue/rest-core/blob/master/example/multi.rb
193
194 ## Supported HTTP clients:
195
6f43c3c @godfat README.md: code, code, code...
godfat authored
196 * `RestCore::RestClient` (gem rest-client)
197 * `RestCore::EmHttpRequest` (gem em-http-request)
198 * `RestCore::Coolio` (gem cool.io)
199 * `RestCore::Auto` (which would pick one of the above depending on the
200 context)
43766b3 @godfat README.md: greatly updated
godfat authored
201
202 ## Build Your Own Middlewares:
203
204 To be added.
205
206 ## Build Your Own HTTP clients:
207
208 To be added.
209
04e2500 @godfat README.md: adding rest-core users
godfat authored
210 ## rest-core users:
211
212 * [topcoder](https://github.com/miaout17/topcoder)
213 * [s2sync](https://github.com/brucehsu/s2sync)
214 * [s2sync_web](https://github.com/brucehsu/s2sync_web)
215
440ab57 @godfat README.md: show build status about master branch; show powered sites
godfat authored
216 ## Powered sites:
217
218 * [PicCollage](http://pic-collage.com/)
219
ba1a6d7 @godfat README.md: add a link to CHANGES
godfat authored
220 ## CHANGES:
221
222 * [CHANGES](https://github.com/cardinalblue/rest-core/blob/master/CHANGES.md)
223
4f1ae1d @godfat README.md: adding glossary, part 1, sorry...
godfat authored
224 ## GLOSSARY:
225
226 * A _client_ is a class which can new connections to make requests.
227 For instance, `RestCore::Facebook.new.get('4')`
228
229 * An _app_ is an HTTP client which would do the underneath HTTP requests.
230 For instance, `RestCore::RestClient` is an HTTP client which uses
231 rest-client gem (`::RestClient`) to make HTTP requests.
232
233 * A _middleware_ is a component for a rest-core stack.
234 For instance, `RestCore::DefaultSite` is a middleware which would add
235 default site URL in front of the request URI if it is not started with
236 http://, thus you can do this: `RestCore::Facebook.get('4')` without
237 specifying where the site (Facebook) it is.
238
239 * `RestCore::Wrapper` is a utility which could help you wrap a number of
240 middlewares into another middleware. Currently, it's used in
241 `RestCore::Buidler` and `RestCore::Cache`.
242
243 * `RestCore::Builder` is a utility which could help you build a _client_
244 with a collection of _middlewares_ and an _app_. i.e. a rest-core stack.
245
246 * `RestCore::Middleware` is a utility which could help you build a non-trivial
247 middleware. More explanation to come...
248
249 * `RestCore::Client` is a module which would be included in a generated
250 _client_ by `RestCore::Builder`. It contains a number of convenient
251 functions which is generally useful.
252
253 * `RestCore::ClientOAuth1` is a module which should be included in a OAuth1.0
254 client. It contains a number of convenient functions which is useful for an
255 OAuth 1.0 client.
256
257 * An `env` is a hash which contains all the information for both request and
258 response. It's mostly seen in `@app.call(env)` See other explanation
259 such as `env[RestCore::REQUEST_METHOD]` for more detail.
260
261 * `env[RestCore::REQUEST_METHOD]` is a symbol representing which HTTP method
262 would be used in the subsequent HTTP request. The possible values are
263 either: `:get`, `:post`, `:put` or `:delete`.
264
265 * `env[RestCore::REQUEST_PATH]` is a string representing which HTTP path
266 would be used in the subsequent HTTP request. This path could also include
267 the protocol, not only the path. e.g. `"http://graph.facebook.com/4"` or
268 simply `"4"`. In the case of built-in Facebook client, the
269 `RestCore::DefaultSite` middleware would take care of the site.
270
05bf4e1 @godfat README.md: finished the GLOSSARY...
godfat authored
271 * `env[RestCore::REQUEST_QUERY]` is a hash which keys are query keys and
272 values are query values. Both keys and values' type should be String, not
273 Symbol. Values with nil or false would be ignored. Both keys and values
274 would be escaped automatically.
275
276 * `env[RestCore::REQUEST_PAYLOAD]` is a hash which keys are payload keys and
277 values are payload values. Both keys and values' type should be String,
278 not Symbol. Values with nil or false would be ignored. Both keys and values
279 would be escaped automatically.
280
281 * `env[RestCore::REQUEST_HEADERS]` is a hash which keys are header names and
282 values are header values. Both keys and values' type should be String,
283 not Symbol. Values with nil or false would be ignored.
284
285 * `env[RestCore::RESPONSE_BODY]` is a string which is returned by the server.
286 Might be nil if there's no response or not yet making HTTP request.
287
288 * `env[RestCore::RESPONSE_STATUS]` is a number which is returned by the
289 server for the HTTP status. Might be nil if there's no response or not
290 yet making HTTP request.
291
292 * `env[RestCore::RESPONSE_HEADERS]` is a hash which is returned by the server
293 for the response headers. Both keys and values' type should be String.
294
5638ecf @godfat rename Ask to Dry
godfat authored
295 * `env[RestCore::DRY]` is a boolean (either `true` or `false` or `nil`) which
296 indicates that if we're only asking for modified `env`, instead of making
05bf4e1 @godfat README.md: finished the GLOSSARY...
godfat authored
297 real requests. It's used to ask for the real request URI, etc.
298
299 * `env[RestCore::FAIL]` is an array which contains failing events. Events
300 could be any objects, it's handled by `RestCore::ErrorDetector` or any
301 other custom _middleware_.
302
303 * `env[RestCore::LOG]` is an array which contains logging events. Events
780051d @godfat README.md: fix copy and paste error
godfat authored
304 could be any objects, it's handled by `RestCore::CommonLogger` or
05bf4e1 @godfat README.md: finished the GLOSSARY...
godfat authored
305 any other custom _middleware_.
4f1ae1d @godfat README.md: adding glossary, part 1, sorry...
godfat authored
306
39fea54 @godfat README.md: move contributors to README.md
godfat authored
307 ## CONTRIBUTORS:
308
309 * Andrew Liu (@eggegg)
310 * andy (@coopsite)
311 * Barnabas Debreczeni (@keo)
312 * Bruce Chu (@bruchu)
313 * Ethan Czahor (@ethanz5)
314 * Florent Vaucelle (@florent)
315 * Jaime Cham (@jcham)
316 * John Fan (@johnfan)
317 * Lin Jen-Shin (@godfat)
318 * Mariusz Pruszynski (@snicky)
319 * Mr. Big Cat (@miaout17)
320 * Nicolas Fouché (@nfo)
321
1a9919e @godfat update Rakefile accordingly, add a stub of README.md, add version file
godfat authored
322 ## LICENSE:
323
a04850b @godfat some formatting
godfat authored
324 Apache License 2.0
1a9919e @godfat update Rakefile accordingly, add a stub of README.md, add version file
godfat authored
325
9f411a1 @godfat it's 2012 now
godfat authored
326 Copyright (c) 2011-2012, Cardinal Blue
1a9919e @godfat update Rakefile accordingly, add a stub of README.md, add version file
godfat authored
327
a04850b @godfat some formatting
godfat authored
328 Licensed under the Apache License, Version 2.0 (the "License");
329 you may not use this file except in compliance with the License.
330 You may obtain a copy of the License at
1a9919e @godfat update Rakefile accordingly, add a stub of README.md, add version file
godfat authored
331
a04850b @godfat some formatting
godfat authored
332 <http://www.apache.org/licenses/LICENSE-2.0>
1a9919e @godfat update Rakefile accordingly, add a stub of README.md, add version file
godfat authored
333
a04850b @godfat some formatting
godfat authored
334 Unless required by applicable law or agreed to in writing, software
335 distributed under the License is distributed on an "AS IS" BASIS,
336 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
337 See the License for the specific language governing permissions and
338 limitations under the License.
Something went wrong with that request. Please try again.