Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 165 lines (117 sloc) 9.55 kB
8f55fce Add a skeleton readme
Darcy Laycock authored
1 # Rocket Pants!
2
98d2351 @Sutto README work and License tweaks
authored
3 First thing's first, you're probably asking yourself - "Why the ridiculous name?". It's simple, really - Rocket Pants is memorable, and sounds completely bad ass. Everything a library needs.
4
5 At it's core, Rails is a set of tools (built around existing toolsets such as ActionPack) to make it easier to build well-designed API's 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 original inspired by but with deeper Rails and ActionPack integration.
6
7 ## Key Features
8
9 Why use Rocket Pants over alternatives like Grape or normal Rails? The reasons we built it come down to a couple of
10 simple things:
11
12 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.
13 2. **Simple and Often Automatic Response Metadata** - Rocket Pants 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 Rocket Pants will do it's best to send as much information back to the user.
14 3. **Extended Error Support** - Rocket Pants has a build 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.
15 4. **It's build on ActionPack** - One of the key differentiators to Graphe is that Rocket Pants embraces ActionPack and uses the modular components included from Rails 3.0 onwards to provide things you're familiar with already such as filters.
16 5. **Semi-efficient Caching Support** - Thanks to a combination of Rails middleware and collection vs. resource distinctions, Rocket Pants makes it relatively easy to implement "Efficient Validation" (See 'http://rtomayko.github.com/rack-cache/faq' [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
17 etags are present.
18 6. **Simple Compact Response** - Want to have your index and search actions return a cut down version of the object whilst the show action returns the full thing? Rocket Pants makes it easy by defaulting to passing in a ` -compact` option when it calls `to_json`.
19
20 ## General Structure
21
22 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.
23
24 Out of the box, we use the following ActionController components:
25
26 * `ActionController::HideActions` - Lets you hide methods from actions.
27 * `ActionController::UrlFor` - `url_for` helpers / tweaks by Rails to make integration with routes work better.
28 * `ActionController::Redirecting` - Allows you to use `redirect_to`.
29 * `ActionController::ConditionalGet` - Adds support for Rails caching controls, e.g. `fresh_when` and `expires_in`.
30 * `ActionController::RackDelegation` - Lets you reset the session and set the response body.
31 * `ActionController::RecordIdentifier` - Gives `dom_class` and `dom_id` methods, used for polymorphic routing.
32 * `ActionController::MimeResponds` - Gives `respond_to` with mime type controls.
33 * `AbstractController::Callbacks` - Adds support for callbacks / filters.
34 * `ActionController::Rescue` - Lets you use `rescue_from`.
35
36 And add our own:
37
38 * `RocketPants::UrlFor` - Automatically includes the current version when generating URLs from the controller.
39 * `RocketPants::Respondable` - The core of RocketPants, the code that handles converting objects to the different container types.
40 * `RocketPants::Versioning` - Allows versioning requirements on the controller to ensure it is only callable with a specific api version.
41 * `RocketPants::Instrumentation` - Adds Instrumentation notifications making it easy to use and hook into with Rails.
42 * `RocketPants::Caching` - Implements time-based caching for index actions and etag-based efficient validation for singular resources.
43 * `RocketPants::ErrorHandling` - Short hand to create errors as well as simplifications to catch and render a standardised error representation.
44 * `RocketPants::Rescuable` - Allows you to hook in to rescuing exceptions and to make it easy to post notifications to tools such as AirBrake.
45
46 To use RocketPants, instead of inheriting from `ActionController::Base`, just inherit from `RocketPants::Base`.
47
48 Likewise, in Rails applications RocketPants also adds `RocketPants::CacheMiddleware` before the controller endpoints to implement
49 ["Efficient Validation"](http://rtomayko.github.com/rack-cache/faq).
50
51 ## Working with data
52
3f8d609 @Sutto More type conversion docs
authored
53 When using RocketPants, you write your controllers the same as how you would with normal ActionController, the only thing that
54 changes is how yoy handle data. `head` and `redirect_to` still work exactly the same as in Rails, but instead of using `respond_with` and
55 `render` you instead use RocketPant's `exposes` methods (and it's kind). Namely:
56
57 - `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).
58 - `paginated` - Render an object as a paginated collection of data.
59 - `collection` - Renders a collection of objects - e.g. an array of users.
60 - `resource` - Renders a single object.
61
62 Along side the above that wrap data, it also provides:
63
64 - `responds` - Renders JSON, normalizing the object first (unwrapped).
65 - `render_json` - Renders an object as JSON.
66
67 ### Singular Resources
68
69 Singular resources will be converted to json via `serializable_hash`, passing through any objects
70 and then wrapped in an object as the `response` key:
71
72 {
73 "response": {
74 "your": "serialized-object"
75 }
76 }
77
78 ### Collections
79
80 Similar to singular resources, but also include extra data about the count of items.
81
82 {
83 "response": [{
84 "name": "object-one"
85 }, {
86 "name": "object-two"
87 }],
88 "count": 2
89 }
90
91 ### Paginated Collections
92
93 The final type, similar to paginated objects but it includes details about the paginated data:
94
95 {
96 "response": [
97 {"name": "object-one"},
98 {"name": "object-two"},
99 {"name": "object-three"},
100 {"name": "object-four"},
101 {"name": "object-five"}
102 ],
103 "count": 5,
104 "pagination": {
105 "previous": 1,
106 "next": 3,
107 "current": 2,
108 "per_page": 5,
109 "count": 23
110 "pages": 5
111 }
112 }
98d2351 @Sutto README work and License tweaks
authored
113
114 ## Registering / Dealing with Errors
115
116 TODO: Explain how to register and invoke errors.
117
118 ## Implementing Efficient Validation
119
120 TODO: Describe how to implement efficient validation.
121
122 ## An Example Controller / App
123
124 TODO: Link to the transperth client here.
73b2f4e Add misc. test helpers
Darcy Laycock authored
125
126 ## Using with Rspec
127
98d2351 @Sutto README work and License tweaks
authored
128 RocketPants includes a set of helpers to make testing controllers built on `RocketPants::Base` simpler.
129
19b8bc5 @Sutto RSpec integration docs
authored
130 * `be_singular_resource` - Checks the response is a single resource - e.g. `response.should be_siingular_resource`.
131 * `be_collection_resource` - Checks the response is collection of resources - e.g. `response.should be_collection_resource`.
132 * `be_paginated_response` - Checks the response is paginated - e.g. `response.should be_paginated_response`.
133 * `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`.
134 * `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`
135
136 Likewise, it adds the following helper methods:
137
138 - `parsed_body` - A parsed-JSON representation of the response.
139 - `decoded_body` - A `Hashie::Mash` of the response body.
140
141 To set up the integration, in your `spec/spec_helper.rb` add:
142
143 config.include RocketPants::TestHelper, :type => :controller
144 cconfig.include RocketPants::RSpecMatchers, :type => :controller
145
146 Inside the `RSpec.configure do |config|` block.
98d2351 @Sutto README work and License tweaks
authored
147
148 ## Contributing
149
150 We encourage all community contributions. Keeping this in mind, please follow these general guidelines when contributing:
151
152 * Fork the project
153 * Create a topic branch for what you’re working on (git checkout -b awesome_feature)
154 * Commit away, push that up (git push your\_remote awesome\_feature)
155 * Create a new GitHub Issue with the commit, asking for review. Alternatively, send a pull request with details of what you added.
156 * 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.
157
158 Other than that, our guidelines very closely match the GemCutter guidelines [here](http://wiki.github.com/qrush/gemcutter/contribution-guidelines).
159
160 (Thanks to [GemCutter](http://wiki.github.com/qrush/gemcutter/) for the contribution guide)
73b2f4e Add misc. test helpers
Darcy Laycock authored
161
98d2351 @Sutto README work and License tweaks
authored
162 ## License
73b2f4e Add misc. test helpers
Darcy Laycock authored
163
98d2351 @Sutto README work and License tweaks
authored
164 API Smith is released under the MIT License (see the [license file](LICENSE)) and is
165 copyright Filter Squad, 2012.
Something went wrong with that request. Please try again.