Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 498 lines (359 sloc) 21.663 kB
3f957e4 @Sutto Add Gemnasium status
authored
1 # RocketPants! [![Build Status](https://secure.travis-ci.org/filtersquad/rocket_pants.png?branch=master)](http://travis-ci.org/filtersquad/rocket_pants) [![Dependency Status](https://gemnasium.com/filtersquad/rocket_pants.png)](https://gemnasium.com/filtersquad/rocket_pants)
2
22b6142 @Sutto More readme tweaks.
authored
3 ## Introduction
4
45ed4af @fredwu Fixed some small typos and enhanced syntax highlighting in the README
fredwu authored
5 First thing's first, you're probably asking yourself - "Why the ridiculous name?". It's simple, really - RocketPants is memorable, and sounds completely bad ass. - everything a library needs.
98d2351 @Sutto README work and License tweaks
authored
6
5e788d8 @levibuzolic Fixed typo in README
levibuzolic authored
7 At its core, RocketPants is a set of tools (built around existing toolsets such as ActionPack) to make it easier to build well-designed APIs in Ruby and more importantly, along side Rails. You can think of it like [Grape](https://github.com/intridea/grape), a fantastic library which RocketPants was originally inspired by but with deeper Rails and ActionPack integration.
98d2351 @Sutto README work and License tweaks
authored
8
9 ## Key Features
10
45ed4af @fredwu Fixed some small typos and enhanced syntax highlighting in the README
fredwu authored
11 Why use RocketPants over alternatives like Grape or normal Rails? The reasons we built it come down to a couple of simple things:
98d2351 @Sutto README work and License tweaks
authored
12
13 1. **It's opinionated** (like Grape) - In this case, we dictate a certain JSON structure we've found nice to work with (after having worked with and investigated a large number of other apis), it makes it simple to add metadata along side requests and the like.
45ed4af @fredwu Fixed some small typos and enhanced syntax highlighting in the README
fredwu authored
14 2. **Simple and Often Automatic Response Metadata** - RocketPants automatically takes care of sending metadata about paginated responses and arrays where possible. This means as a user, you only need to worry about writing `expose object_or_presenter` in your controller and RocketPants will do it's best to send as much information back to the user.
15 3. **Extended Error Support** - RocketPants has a built in framework to manage errors it knows how to handle (in the forms of mapping exceptions to a well defined JSON structure) as well as tools to make it simple to hook up to Airbrake and do things such as including an error identifier in the response.
16 4. **It's built on ActionPack** - One of the key differentiators to Grape is that RocketPants embraces ActionPack and uses the modular components included from Rails 3.0 onwards to provide things you're familiar with already such as filters.
17 5. **Semi-efficient Caching Support** - Thanks to a combination of Rails middleware and collection vs. resource distinctions, RocketPants makes it relatively easy to implement "Efficient Validation" (See [here](http://rtomayko.github.com/rack-cache/faq)). As a developer, this means you get even more benefits of http caching where possible, without the need to generate full requests when etags are present.
0222651 @Sutto Add client examples
authored
18 6. **Simple tools to consume RocketPants apis** - RocketPants includes the `RocketPants::Client` class which builds upon [APISmith](https://github.com/filtersquad/api_smith) to make it easier to build clients e.g. automatically converting paginated responses back.
9d28bed @Sutto Add in more docs
authored
19 7. **Build in Header Metadata Support** - APIs can easily expose `Link:` headers (it's even partly built in for paginated data - see below) and request metadata (e.g. Object count etc) can easily be embedded in the headers of the response, making useful `HEAD` requests.
20 8. **Out of the Box ActiveRecord mapping** - We'll automatically take care of mapping `ActiveRecord::RecordNotFound`, `ActiveRecord::RecordNotSaved` and `ActiveRecord::RecordInvalid` for you, even including validation messages where possible.
98d2351 @Sutto README work and License tweaks
authored
21
22b6142 @Sutto More readme tweaks.
authored
22 ## Examples
23
24 ### A full example application
74b4567 @Sutto Add link to example app (not yet there)
authored
25
45ed4af @fredwu Fixed some small typos and enhanced syntax highlighting in the README
fredwu authored
26 Learn better by reading code? There is also have an example app mixing models and api clients over at [Sutto/transperth-api](https://github.com/Sutto/transperth-api) that is built using RocketPants.
74b4567 @Sutto Add link to example app (not yet there)
authored
27
0222651 @Sutto Add client examples
authored
28 ### Example Server Code
22b6142 @Sutto More readme tweaks.
authored
29
7a362ce @Sutto More tweaks! Namely to the README
authored
30 Say, for example, you have a basic Food model:
22b6142 @Sutto More readme tweaks.
authored
31
32 ```ruby
7a362ce @Sutto More tweaks! Namely to the README
authored
33 class Food < ActiveRecord::Base
34 include RocketPants::Cacheable
35 end
36 ```
37
38 ```ruby
39 class FoodsController < RocketPants::Base
40
41 version 1
42
43 # The list of foods is paginated for 5 minutes, the food itself is cached
44 # until it's modified (using Efficient Validation)
45 caches :index, :show, :caches_for => 5.minutes
22b6142 @Sutto More readme tweaks.
authored
46
47 def index
7a362ce @Sutto More tweaks! Namely to the README
authored
48 expose Food.paginate(:page => params[:page])
22b6142 @Sutto More readme tweaks.
authored
49 end
50
51 def show
7a362ce @Sutto More tweaks! Namely to the README
authored
52 expose Food.find(params[:id])
22b6142 @Sutto More readme tweaks.
authored
53 end
54
55 end
56 ```
57
58 And in the router we'd just use the normal REST-like routes in Rails:
59
60 ```ruby
7a362ce @Sutto More tweaks! Namely to the README
authored
61 api :version => 1 do
62 resources :foods, :only => [:index, :show]
63 end
64 ```
65
d6092e9 @Sutto We need the version in the URL
authored
66 And then, using this example, hitting `GET http://localhost:3000/1/foods` would result in:
7a362ce @Sutto More tweaks! Namely to the README
authored
67
68 ```json
69 {
70 "response": [{
71 "id": 1,
72 "name": "Delicious Food"
73 }, {
74 "id": 2,
75 "name": "More Delicious Food"
76 }],
77 "count": 2,
78 "pagination": {
79 "previous": nil,
80 "next": nil,
81 "current": 1,
82 "per_page": 10,
83 "count": 2,
84 "pages": 1
85 }
86 }
22b6142 @Sutto More readme tweaks.
authored
87 ```
88
d6092e9 @Sutto We need the version in the URL
authored
89 with the `Cache-Control` header set whilst hitting `GET http://localhost:3000/1/foods/1` would return:
7a362ce @Sutto More tweaks! Namely to the README
authored
90
91 ```json
92 {
93 "response": {
94 "id": 1,
95 "name": "Delicious Food"
96 }
97 }
98 ```
99
100 with the `Etag` header set.
101
aa5dc16 @Sutto Add JSONP notes
authored
102 #### JSONP
103
104 If you want to enable JSONP support, it's as simple as calling `jsonp` in your class method:
105
106 ```ruby
107 class MyController < RocketPants::Base
108 jsonp
109 end
110 ```
111
112 By default this will use the `callback` parameter, e.g. `GET /1/my?callback=console.log`.
113 To change this parameter, specify the `parameter` option like so:
114
115 ```ruby
116 class MyController < RocketPants::Base
117 jsonp :parameter => :jsonp
118 end
119 ```
120
121 Finally, to disable it in a subclass, simple call `jsonp` in the child and pass `:enable => false` as an option.
122
6c3caed @Sutto Initial link documentation
authored
123 #### Header Metadata
124
125 When `RocketPants.header_metadata` or `config.rocket_pants.header_metadata` are set to true, RocketPants can automatically
126 expose metadata via `X-Api-` headers. Likewise, for paginated responses, if you implement `page_url(page_number)` in your controller
127 with header metadata enabled, RocketPants will automatically add HTTP Link Headers for the next, prev, first and last to your
128 response.
129
130 Likewise, you can manually add link headers using the `link(rel, href, attributes = {})` method like so:
131
132 ```ruby
133 def index
134 # Not an actual rel, just an example...
135 link :profile, user_profile_path(current_user)
136 expose current_user
137 end
138 ```
139
140 For batch adding links, you can use the `links` method:
141
142 ```ruby
143 def index
144 # Probably not the best example...
145 links :next => random_wallpaper_path, :prev => random_wallpaper_path
146 expose Wallpaper.random
147 end
148 ```
149
0222651 @Sutto Add client examples
authored
150 ### Example Client Code
151
152 Using the example above, we could then use the following to write a client:
153
154 ```ruby
155 class FoodsClient < RocketPants::Client
156
157 version 1
158 base_uri 'http://localhost:3000'
159
160 class Food < APISmith::Smash
161 property :id
162 property :name
163 end
164
165 def foods
166 get 'foods', :transformer => Food
167 end
168
169 def food(id)
170 get "foods/#{id}", :transformer => Food
171 end
172
173 end
174 ```
175
98d2351 @Sutto README work and License tweaks
authored
176 ## General Structure
177
178 RocketPants builds upon the mixin-based approach to ActionController-based rails applications that Rails 3 made possible. Instead of including everything like Rails does in `ActionController::Base`, RocketPants only includes the bare minimum to make apis. In the near future, it may be modified to work with `ActionController::Base` for the purposes of better compatibility with other gems.
179
180 Out of the box, we use the following ActionController components:
181
182 * `ActionController::HideActions` - Lets you hide methods from actions.
183 * `ActionController::UrlFor` - `url_for` helpers / tweaks by Rails to make integration with routes work better.
184 * `ActionController::Redirecting` - Allows you to use `redirect_to`.
185 * `ActionController::ConditionalGet` - Adds support for Rails caching controls, e.g. `fresh_when` and `expires_in`.
186 * `ActionController::RackDelegation` - Lets you reset the session and set the response body.
187 * `ActionController::RecordIdentifier` - Gives `dom_class` and `dom_id` methods, used for polymorphic routing.
9858dfb @Sutto Readme updates
authored
188 * `ActionController::HttpAuthentication` Mixins - Gives Token, Digest and Basic authentication.
98d2351 @Sutto README work and License tweaks
authored
189 * `AbstractController::Callbacks` - Adds support for callbacks / filters.
190 * `ActionController::Rescue` - Lets you use `rescue_from`.
191
45ed4af @fredwu Fixed some small typos and enhanced syntax highlighting in the README
fredwu authored
192 And added our own:
98d2351 @Sutto README work and License tweaks
authored
193
194 * `RocketPants::UrlFor` - Automatically includes the current version when generating URLs from the controller.
195 * `RocketPants::Respondable` - The core of RocketPants, the code that handles converting objects to the different container types.
196 * `RocketPants::Versioning` - Allows versioning requirements on the controller to ensure it is only callable with a specific api version.
197 * `RocketPants::Instrumentation` - Adds Instrumentation notifications making it easy to use and hook into with Rails.
198 * `RocketPants::Caching` - Implements time-based caching for index actions and etag-based efficient validation for singular resources.
199 * `RocketPants::ErrorHandling` - Short hand to create errors as well as simplifications to catch and render a standardised error representation.
200 * `RocketPants::Rescuable` - Allows you to hook in to rescuing exceptions and to make it easy to post notifications to tools such as AirBrake.
201
202 To use RocketPants, instead of inheriting from `ActionController::Base`, just inherit from `RocketPants::Base`.
203
45ed4af @fredwu Fixed some small typos and enhanced syntax highlighting in the README
fredwu authored
204 Likewise, in Rails applications RocketPants also adds `RocketPants::CacheMiddleware` before the controller endpoints to implement ["Efficient Validation"](http://rtomayko.github.com/rack-cache/faq).
98d2351 @Sutto README work and License tweaks
authored
205
149db46 @Sutto More README docs / tweaks
authored
206 ## Installing RocketPants
207
208 Installing RocketPants is a simple matter of adding:
209
210 gem 'rocket_pants', '~> 1.0'
211
45ed4af @fredwu Fixed some small typos and enhanced syntax highlighting in the README
fredwu authored
212 To your `Gemfile` and running `bundle install`. Next, instead of inherited from `ActionController::Base`, simply inherit from `RocketPants::Base` instead. If you're working with an API-only application, I typically change this in `ApplicationController` and inherit from `ApplicationController` as usual. Otherwise, I generate a new `ApiController` base controller along side `ApplicationController` which instead inherits from `RocketPants::Base` and place all my logic there.
149db46 @Sutto More README docs / tweaks
authored
213
214 ## Configuration
215
45ed4af @fredwu Fixed some small typos and enhanced syntax highlighting in the README
fredwu authored
216 Setting up RocketPants in your rails application is pretty simple and requires a minimal amount of effort. Inside your environment configuration, RocketPants offers the following options to control how it's configured (and their expanded alternatives):
149db46 @Sutto More README docs / tweaks
authored
217
218 - `config.rocket_pants.use_caching` - Defaulting to true for production environments and false elsewhere, defines whether RocketPants caching setup as described below is used.
45ed4af @fredwu Fixed some small typos and enhanced syntax highlighting in the README
fredwu authored
219 - `config.rocket_pants.cache` - A `Moneta::Store` instance used as the RocketPants cache, defaulting to a moneta memory instance. Change for proper caching. (See [here](https://github.com/wycats/moneta) for more information on Moneta.)
6b2a363 @Sutto Update the readme with configuration documentation
authored
220 - `config.rocket_pants.header_metadata` - Defaults to false, if true enables header metadata in the application.
221 - `config.rocket_pants.pass_through_errors` - Defaults true in development and test, false otherwise. If true, will pass through errors up the stack otherwise will swallow them and return a system error via JSON for any unhandled exceptions.
149db46 @Sutto More README docs / tweaks
authored
222
223 ## Version Controllers / Routes
224
45ed4af @fredwu Fixed some small typos and enhanced syntax highlighting in the README
fredwu authored
225 The current preferred way of dealing with version APIs in RocketPants is to do it using routes in the form of `/:version/:endpoint` - e.g. `GET /1/users/324`. RocketPants has support in the router and controller level for enforcing and controlling this. In the controller, it's a matter of specifying the required API versions:
149db46 @Sutto More README docs / tweaks
authored
226
45ed4af @fredwu Fixed some small typos and enhanced syntax highlighting in the README
fredwu authored
227 ```ruby
228 class UsersController < RocketPants::Base
229 version 1 # A single version
230 # or...
231 version 2..3 # 2-3 support this controller
232 end
233 ```
149db46 @Sutto More README docs / tweaks
authored
234
45ed4af @fredwu Fixed some small typos and enhanced syntax highlighting in the README
fredwu authored
235 And in the case of multiple versions, I strongly encourage namespaces the controllers inside modules. If the version param (as specified) by the URL does not match, then the specified controller will return an `:invalid_version` error as shown below.
149db46 @Sutto More README docs / tweaks
authored
236
237 Next, in your `config/routes.rb` file, you can also declare versions using the following syntax and it will automatically set up the routes for you:
238
45ed4af @fredwu Fixed some small typos and enhanced syntax highlighting in the README
fredwu authored
239 ```ruby
240 api :version => 1 do
241 get 'x', :to => 'test#item'
242 end
243 ```
149db46 @Sutto More README docs / tweaks
authored
244
245 Which will route `GET /1/x` to `TestController#item`.
246
247 Likewise, you can specify a route for multiple versions by:
248
45ed4af @fredwu Fixed some small typos and enhanced syntax highlighting in the README
fredwu authored
249 ```ruby
250 api :versions => 1..3 do
251 get 'x', :to => 'test#item'
252 end
253 ```
149db46 @Sutto More README docs / tweaks
authored
254
98d2351 @Sutto README work and License tweaks
authored
255 ## Working with data
256
45ed4af @fredwu Fixed some small typos and enhanced syntax highlighting in the README
fredwu authored
257 When using RocketPants, you write your controllers the same as how you would with normal ActionController, the only thing that changes is how you handle data. `head` and `redirect_to` still work exactly the same as in Rails, but instead of using `respond_with` and `render` you instead use RocketPant's `exposes` methods (and it's kind). Namely:
3f8d609 @Sutto More type conversion docs
authored
258
259 - `expose` / `exposes` - The core of all type conversion, will check the type of data and automatically convert it to the correct time (for either a singular, collection or paginated resource).
260 - `paginated` - Render an object as a paginated collection of data.
261 - `collection` - Renders a collection of objects - e.g. an array of users.
262 - `resource` - Renders a single object.
263
264 Along side the above that wrap data, it also provides:
265
266 - `responds` - Renders JSON, normalizing the object first (unwrapped).
267 - `render_json` - Renders an object as JSON.
268
269 ### Singular Resources
270
45ed4af @fredwu Fixed some small typos and enhanced syntax highlighting in the README
fredwu authored
271 Singular resources will be converted to JSON via `serializable_hash`, passing through any objects
3f8d609 @Sutto More type conversion docs
authored
272 and then wrapped in an object as the `response` key:
273
45ed4af @fredwu Fixed some small typos and enhanced syntax highlighting in the README
fredwu authored
274 ```json
275 {
276 "response": {
277 "your": "serialized-object"
278 }
279 }
280 ```
3f8d609 @Sutto More type conversion docs
authored
281
282 ### Collections
283
284 Similar to singular resources, but also include extra data about the count of items.
285
45ed4af @fredwu Fixed some small typos and enhanced syntax highlighting in the README
fredwu authored
286 ```json
287 {
288 "response": [{
289 "name": "object-one"
290 }, {
291 "name": "object-two"
292 }],
293 "count": 2
294 }
295 ```
3f8d609 @Sutto More type conversion docs
authored
296
297 ### Paginated Collections
298
c741f37 @paxer typo fix
paxer authored
299 The final type, similar to collection objects but it includes details about the paginated data:
3f8d609 @Sutto More type conversion docs
authored
300
45ed4af @fredwu Fixed some small typos and enhanced syntax highlighting in the README
fredwu authored
301 ```json
302 {
303 "response": [
304 {"name": "object-one"},
305 {"name": "object-two"},
306 {"name": "object-three"},
307 {"name": "object-four"},
308 {"name": "object-five"}
309 ],
310 "count": 5,
311 "pagination": {
312 "previous": 1,
313 "next": 3,
314 "current": 2,
315 "per_page": 5,
1e498dc @levibuzolic Missing comma in paginated collections example
levibuzolic authored
316 "count": 23,
45ed4af @fredwu Fixed some small typos and enhanced syntax highlighting in the README
fredwu authored
317 "pages": 5
318 }
319 }
320 ```
98d2351 @Sutto README work and License tweaks
authored
321
322 ## Registering / Dealing with Errors
323
45ed4af @fredwu Fixed some small typos and enhanced syntax highlighting in the README
fredwu authored
324 One of the built in features of RocketPants is the ability to handle rescuing / controlling exceptions and more importantly to handle mapping exceptions to names, messages and error codes.
4da07ec @Sutto Started writing docs on the error handling
authored
325
a270612 @Sutto Add ActiveRecord integration and specs, docs!
authored
326 This comes in useful when you wish to automatically convert exceptions such as `ActiveRecord::RecordNotFound` (Note: This case is handled already) to a structured bit of data in the response. Namely, it makes it trivial to generate objects that follow the JSON structure of:
4da07ec @Sutto Started writing docs on the error handling
authored
327
45ed4af @fredwu Fixed some small typos and enhanced syntax highlighting in the README
fredwu authored
328 ```json
329 {
330 "error": "standard_error_name",
331 "error_description": "A translated error message describing what happened."
332 }
333 ```
4da07ec @Sutto Started writing docs on the error handling
authored
334
335 It also adds a facilities to make it easy to add extra information to the response.
336
337 RocketPants will also attempt to convert all errors in the controller, defaulting to the `"system"` exception name and message as the error description. We also provide a registry to allow throwing exception from their symbolic name like so:
338
45ed4af @fredwu Fixed some small typos and enhanced syntax highlighting in the README
fredwu authored
339 ```ruby
340 error! :not_found
341 ```
4da07ec @Sutto Started writing docs on the error handling
authored
342
343 In the controller.
344
345 Out of the box, the following exceptions come pre-registered and setup:
346
347 - `:throttled` - The user has hit an api throttled error.
348 - `:unauthenticated` - The user doesn't have valid authentication details.
349 - `:invalid_version` - An invalid API version was specified.
350 - `:not_implemented` - The specified endpoint is not yet implemented.
351 - `:not_found` - The given resource could not be found.
a270612 @Sutto Add ActiveRecord integration and specs, docs!
authored
352 - `:invalid_resource` - The given resource was invalid.
353 - `:bad_request` - The given request was not as expected.
4da07ec @Sutto Started writing docs on the error handling
authored
354
6d970f0 @Sutto Add error context extras to the README
authored
355 Note that error also excepts a Hash of contextual options, many which will be passed through to the Rails I18N subsystem. E.g:
356
357 ```ruby
358 error! :throttled, :max_per_hour => 100
359 ```
360
361 Will look up the translation `rocket_pants.errors.throttled` in your I18N files, and call them with `:max_per_hour` as an argument.
362
363 Finally, You can use this to also pass custom values to include in the response, e.g:
364
365 ```ruby
366 error! :throttled, :extras => {:code => 123}
367 ```
368
369 Will return something similar to:
370
371 ```json
372 {
373 "error": "throttled",
374 "error_description": "The example error message goes here",
375 "code": 123
376 }
377 ```
378
a270612 @Sutto Add ActiveRecord integration and specs, docs!
authored
379 ### Build in ActiveRecord Errors
380
381 Out of the box, Rocket Pants will automatically map the following to built in errors and rescue them
382 as appropriate.
383
384 - `ActiveRecord::RecordNotFound` into `RocketPants::NotFound`
385 - `ActiveRecord::RecordNotSaved` into `RocketPants::InvalidResource (with no validation messages).`
386 - `ActiveRecord::RecordInvalid` into `RocketPants::InvalidResource (with messages in the "messages" key of the JSON).`
387
388 For Invalid Resource messages, the response looks roughly akin to:
389
9d28bed @Sutto Add in more docs
authored
390 ```json
391 {
392 "error": "invalid_resource",
393 "error_description": "The current resource was deemed invalid.",
394 "messages": {
395 "name": ["can't be blank"],
396 "child_number":["can't be blank", "is not a number"],
397 "latin_name": ["is too short (minimum is 5 characters)", "is invalid"]
398 }
399 }
400 ```
a270612 @Sutto Add ActiveRecord integration and specs, docs!
authored
401
98d2351 @Sutto README work and License tweaks
authored
402 ## Implementing Efficient Validation
403
45ed4af @fredwu Fixed some small typos and enhanced syntax highlighting in the README
fredwu authored
404 One of the core design principles built into RocketPants is simple support for "Efficient Validation" as described in the [Rack::Cache FAQ](http://rtomayko.github.com/rack-cache/faq) - Namely, it adds simple support for object-level caching using etags with fast verification thanks to the `RocketPants::CacheMiddleware` cache middleware.
149db46 @Sutto More README docs / tweaks
authored
405
45ed4af @fredwu Fixed some small typos and enhanced syntax highlighting in the README
fredwu authored
406 To do this, it uses `RocketPants.cache`, by default any Moneta-based store, to keep a mapping of object -> current cache key. RocketPants will then generate the etag when caching is enabled in the controller for singular-responses, generating an etag that can be quickly validated.
149db46 @Sutto More README docs / tweaks
authored
407
408 For example, you'd add the following to your model:
409
45ed4af @fredwu Fixed some small typos and enhanced syntax highlighting in the README
fredwu authored
410 ```ruby
411 class User < ActiveRecord::Base
412 include RocketPants::Cacheable
413 end
414 ```
149db46 @Sutto More README docs / tweaks
authored
415
416 And then in your controller, you'd have something like:
417
45ed4af @fredwu Fixed some small typos and enhanced syntax highlighting in the README
fredwu authored
418 ```ruby
419 class UsersController < RocketPants::Base
149db46 @Sutto More README docs / tweaks
authored
420
45ed4af @fredwu Fixed some small typos and enhanced syntax highlighting in the README
fredwu authored
421 version 1
149db46 @Sutto More README docs / tweaks
authored
422
45ed4af @fredwu Fixed some small typos and enhanced syntax highlighting in the README
fredwu authored
423 # Time based, e.g. collections, will be cached for 5 minutes - whilst singular
424 # items e.g. show will use etag-based caching:
425 caches :show, :index, :caches_for => 5.minutes
149db46 @Sutto More README docs / tweaks
authored
426
45ed4af @fredwu Fixed some small typos and enhanced syntax highlighting in the README
fredwu authored
427 def index
428 expose User.all
429 end
149db46 @Sutto More README docs / tweaks
authored
430
45ed4af @fredwu Fixed some small typos and enhanced syntax highlighting in the README
fredwu authored
431 def show
432 expose User.find(params[:id])
433 end
149db46 @Sutto More README docs / tweaks
authored
434
45ed4af @fredwu Fixed some small typos and enhanced syntax highlighting in the README
fredwu authored
435 end
436 ```
149db46 @Sutto More README docs / tweaks
authored
437
45ed4af @fredwu Fixed some small typos and enhanced syntax highlighting in the README
fredwu authored
438 When the user hits the index endpoint, it will generate an expiry-based caching header that caches the result for up to 5 minutes. When the user instead hits the show endpoint, it will generate a special etag that contains and object identifier portion and an object cache key. Inside `RocketPants.cache`, we store the mapping and then inside `RocketPants::CacheMiddleware`, we simply check if the given cache key matches the specified object identifier. If it does, we return a not modified response otherwise we pass it through to controller - giving the advantage of efficient caching without having to hit the full database on every request.
98d2351 @Sutto README work and License tweaks
authored
439
45ed4af @fredwu Fixed some small typos and enhanced syntax highlighting in the README
fredwu authored
440 ## Using with RSpec
73b2f4e Add misc. test helpers
Darcy Laycock authored
441
f0a3bbd @Sutto Update README.md to mention needing the version parameters in specs. …
authored
442 When testing controllers written using RocketPants, your normal rails approach should work.
443 The only difference one needs to take into the account is the need to specify the `:version`
444 parameter on any http requests, e.g:
445
446 ```ruby
447 get :index, :version => 1
448 ```
449
450 Otherwise it will raise an exception.
451
98d2351 @Sutto README work and License tweaks
authored
452 RocketPants includes a set of helpers to make testing controllers built on `RocketPants::Base` simpler.
453
19b8bc5 @Sutto RSpec integration docs
authored
454 * `be_singular_resource` - Checks the response is a single resource - e.g. `response.should be_siingular_resource`.
455 * `be_collection_resource` - Checks the response is collection of resources - e.g. `response.should be_collection_resource`.
e7f4299 @Sutto Finish implementing jsonp, add a stubbed out helper_method implementa…
authored
456 * `be_paginated_resource` - Checks the response is paginated - e.g. `response.should be_paginated_resource`.
19b8bc5 @Sutto RSpec integration docs
authored
457 * `be_api_error(type = any)` - Checks it returned an error for the specified exception (or check the response is an error without any argument) - e.g. `response.should be_api_error RocketPants::NotFound`.
458 * `have_exposed(data, options = {})` - Given an object and conversion options, lets you check the output exposed the same object. e.g: `response.should have_exposed user`
459
460 Likewise, it adds the following helper methods:
461
462 - `parsed_body` - A parsed-JSON representation of the response.
463 - `decoded_body` - A `Hashie::Mash` of the response body.
464
465 To set up the integration, in your `spec/spec_helper.rb` add:
466
45ed4af @fredwu Fixed some small typos and enhanced syntax highlighting in the README
fredwu authored
467 ```ruby
468 config.include RocketPants::TestHelper, :type => :controller
469 config.include RocketPants::RSpecMatchers, :type => :controller
470 ```
19b8bc5 @Sutto RSpec integration docs
authored
471
472 Inside the `RSpec.configure do |config|` block.
98d2351 @Sutto README work and License tweaks
authored
473
8ced3cb @Sutto Update README.md
authored
474 ## Contributors
475
476 - [Darcy Laycock](https://github.com/Sutto) - Main developer, current maintainer.
477 - [Steve Webb](https://github.com/swebb) - Helped with original work at [The Frontier Group](https://github.com/thefrontiergroup), inc. original design.
478 - [Fred Wu](https://github.com/fredwu) - README fixes.
479 - [Levi Buzolic](https://github.com/levibuzolic) - README fixes.
480
98d2351 @Sutto README work and License tweaks
authored
481 ## Contributing
482
483 We encourage all community contributions. Keeping this in mind, please follow these general guidelines when contributing:
484
485 * Fork the project
486 * Create a topic branch for what you’re working on (git checkout -b awesome_feature)
487 * Commit away, push that up (git push your\_remote awesome\_feature)
488 * Create a new GitHub Issue with the commit, asking for review. Alternatively, send a pull request with details of what you added.
489 * Once it’s accepted, if you want access to the core repository feel free to ask! Otherwise, you can continue to hack away in your own fork.
490
491 Other than that, our guidelines very closely match the GemCutter guidelines [here](http://wiki.github.com/qrush/gemcutter/contribution-guidelines).
492
493 (Thanks to [GemCutter](http://wiki.github.com/qrush/gemcutter/) for the contribution guide)
73b2f4e Add misc. test helpers
Darcy Laycock authored
494
98d2351 @Sutto README work and License tweaks
authored
495 ## License
73b2f4e Add misc. test helpers
Darcy Laycock authored
496
22b6142 @Sutto More readme tweaks.
authored
497 RocketPants is released under the MIT License (see the [license file](https://github.com/filtersquad/rocket_pants/blob/master/LICENSE)) and is copyright Filter Squad, 2012.
Something went wrong with that request. Please try again.