Name: snorlax
Owner: Loomio
Description: Snorlax is an opinionated, flexible and well-RESTed controller for Rails APIs
Created: 2015-08-07 06:42:33.0
Updated: 2018-05-20 22:43:27.0
Pushed: 2018-05-20 22:43:26.0
Homepage: null
Size: 26
Language: Ruby
GitHub Committers
| User | Most Recent Commit | # Commits |
|---|
Other Committers
| User | Most Recent Commit | # Commits |
|---|
Snorlax is an opinionated, flexible, and well-RESTed gem for building Rails APIs. It's designed to Do The Right Thing? by default, but allow you to customize where necessary.
It's been extracted from Loomio.
Add this line to your application's Gemfile:
'snorlax'
And then execute:
$ bundle
Or install it yourself as:
$ gem install snorlax
There are two primary ways to use Snorlax. The easier way is to inherit from it:
s MyController < Snorlax::Base
But, if you're already inheriting from something else, Snorlax makes it easy to simply apply itself to your controller without being a parent, by calling snorlax_used_rest! like so:
s MyController < SomeOtherController
orlax_used_rest!
Once you've got it installed, you're good to go!
Snorlax is designed to provide a set of flexible API endpoints for client side consumption. It uses side loading, which means that all of the records returned are unnested and easily available for consumption.
By default, Snorlax will fetch the requested model by id using the ActiveModel::Base.find method. To override this behaviour, you may override the load_resource method in your controller.
s TaurosController < Snorlax::Base
f load_resource
SafariZone.find(params[:id])
d
NB: This would be a great place to ensure that the current user is allowed to view the requested resource.
Snorlax DEMANDS that you define two separate methods for the index action to work properly:
public_records - records which are available publicly (ie, they can be viewed even if current_user is nil)visible_records - records which the current user is allowed to access.s StaryusController < Snorlax::Base
f public_records
Staryu.visible_to_public
d
f visible_records
current_user.staryus
d
If these are the same, you may override the accessible_records method instead
s StarmiesController < Snorlax::Base
f accessible_records
Starmie.all
d
The default index action look like this:
index
stantiate_collection
spond_with_collection
but there are many options to customize it.
A Snorlax controller can accept from and per parameters for paging. For example,
/vi/psyducks?from=0&per=100
will return the first 100 psyducks within the accessible records.
If no from or per params are provided, Snorlax will default to the first 50 records. (from = 0, per = 50)
You can override the default page size by overriding the default_page_size method.
s WobbuffetsController < Snorlax::Base
f default_page_size
25
d
A Snorlax controller can accept since and until parameters for timeframing. The date it looks for defaults to created_at. For example,
/v1/charmanders?since=11-11-2011&until=12-12-2012
will return charmanders which were created between Nov 11, 2011, and Dec 12, 2012.
You can override the datetime column the query looks at by passing the timeframe_for option. For example,
/v1/charmeleons?since=11-11-2011&until=12-12-2012&timeframe_for=evolved_at
will return charmeleons which evolved between Nov 11, 2011, and Dec 12, 2012
Since and until can be in any format that Date.parse will accept.
If you want to disallow timeframing and/or pagination for a particular action, simple pass timeframe_collection: false or page_collection: false when the collection is instantiated.
s SquirtlesController < Snorlax::Base
f all_squirtles
instantiate_collection page_collection: false, timeframe_collection: false
respond_with_collection
d
Snorlax also provides a dead simple way to provide your own filters, in addition to and in combination with the ones provided.
You can do this by passing a block to the instantiate_collection method in your controller action. For example,
s ChanseysController < Snorlax::Base
f sleeping
instantiate_collection { |collection| collection.where(sleeping: true) }
respond_with_collection
d
Will return all sleeping Chanseys. (This can be combined with timeframing and paginating as well.) (NB: this filtering happens before the collection is paginated or timeframed, so it's a good opportunity to add additional filters or apply an order to your records. Or both!)
By default, Snorlax will find a serializer based on the controller name, and serialize out your collection of records with a root.
You can override the serializer being used or the serializer root across the controller by defining a resource_serializer or serializer_root method, respectively:
s DittosController < Snorlax::Base
f resource_serializer
PokemonSerializer
d
f serializer_root
:pokemon
d
This will result is JSON like this:
kemon: [{ pokemon_serializer_field_a: 'valueA', pokemon_serializer_field_b: 'valueB' }] }
To do this for a particular action, pass the serializer or root option to respond_with_collection.
(NB: You can also pass a scope to the serializer in this way, by passing a 'scope' option)
s DittosController < Snorlax::Base
f index
instantiate_collection
respond_with_collection serializer: PokemonSerializer, root: :pokemon, scope: { is_ditto: true }
d
By default, Snorlax will load the requested resource, perform an action on it, and then respond with the resource (with the same response as the show action) It looks like this:
create
stantiate_resource
eate_action
spond_with_resource
create_action
source.save
If you have more complicated logic for creating or updating records (your creation / update logic is wrapped up in a service object, for example), simply override the create_action method (or the update_action method in the case of update)
MewtwosController < Snorlax::Base
f create_action
Science.faff_about(resource_params)
d
(NB: this is a good opportunity to make sure that the current user has permission to modify the record.)
respond_with_resource accepts the same parameters as respond_with_collection, to allow for single-action customization of the json response.
MewtwosController < Snorlax::Base
f create
instantiate_resource
create_action
respond_with_resource { serializer: LegendarySerializer, root: 'legendary_pokemon' }
d
TODO: explain the respond_with_errors behaviour
Bug reports and pull requests are welcome on GitHub at https://github.com/gdpelican/snorlax. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.
The gem is available as open source under the terms of the MIT License.