Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 106 lines (70 sloc) 7.689 kb
8f55fce Add a skeleton readme
Darcy Laycock authored
1 # Rocket Pants!
2
98d2351 Darcy Laycock 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
53 TODO: explain how exposing data works.
54
55 ## Registering / Dealing with Errors
56
57 TODO: Explain how to register and invoke errors.
58
59 ## Implementing Efficient Validation
60
61 TODO: Describe how to implement efficient validation.
62
63 ## An Example Controller / App
64
65 TODO: Link to the transperth client here.
73b2f4e Add misc. test helpers
Darcy Laycock authored
66
67 ## Using with Rspec
68
98d2351 Darcy Laycock README work and License tweaks
authored
69 RocketPants includes a set of helpers to make testing controllers built on `RocketPants::Base` simpler.
70
19b8bc5 Darcy Laycock RSpec integration docs
authored
71 * `be_singular_resource` - Checks the response is a single resource - e.g. `response.should be_siingular_resource`.
72 * `be_collection_resource` - Checks the response is collection of resources - e.g. `response.should be_collection_resource`.
73 * `be_paginated_response` - Checks the response is paginated - e.g. `response.should be_paginated_response`.
74 * `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`.
75 * `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`
76
77 Likewise, it adds the following helper methods:
78
79 - `parsed_body` - A parsed-JSON representation of the response.
80 - `decoded_body` - A `Hashie::Mash` of the response body.
81
82 To set up the integration, in your `spec/spec_helper.rb` add:
83
84 config.include RocketPants::TestHelper, :type => :controller
85 cconfig.include RocketPants::RSpecMatchers, :type => :controller
86
87 Inside the `RSpec.configure do |config|` block.
98d2351 Darcy Laycock README work and License tweaks
authored
88
89 ## Contributing
90
91 We encourage all community contributions. Keeping this in mind, please follow these general guidelines when contributing:
92
93 * Fork the project
94 * Create a topic branch for what you’re working on (git checkout -b awesome_feature)
95 * Commit away, push that up (git push your\_remote awesome\_feature)
96 * Create a new GitHub Issue with the commit, asking for review. Alternatively, send a pull request with details of what you added.
97 * 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.
98
99 Other than that, our guidelines very closely match the GemCutter guidelines [here](http://wiki.github.com/qrush/gemcutter/contribution-guidelines).
100
101 (Thanks to [GemCutter](http://wiki.github.com/qrush/gemcutter/) for the contribution guide)
73b2f4e Add misc. test helpers
Darcy Laycock authored
102
98d2351 Darcy Laycock README work and License tweaks
authored
103 ## License
73b2f4e Add misc. test helpers
Darcy Laycock authored
104
98d2351 Darcy Laycock README work and License tweaks
authored
105 API Smith is released under the MIT License (see the [license file](LICENSE)) and is
106 copyright Filter Squad, 2012.
Something went wrong with that request. Please try again.