snorlax 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d6d01c9be95a6a09f2b95508b9a7bd95a7df93a2
-  data.tar.gz: 4ca7cea8aa4a0113e8ef3384591c6e0af7ff6a73
+  metadata.gz: c17a98c1013d790464bb3a26a6664777e239eafc
+  data.tar.gz: 528dfab11bd3262d06c38c7e95cdaadfba38c20a
 SHA512:
-  metadata.gz: cecf771da9bcd04f93d194be38584813941bfd7bbd38f2b96e3dd7877c9ff4a705de4896762c1c87e1c00605f42245fd8ee4efb45a5d458b9a496c11614dd52f
-  data.tar.gz: 175f940f1daacce9d660aeaa2fc03314b717bde28d7036dfc695a0d1e6ea0f81b91906e57d16e92d5292eda78373d5294c0bbc1650c0a66f87a3c1cca6766d28
+  metadata.gz: 98972fe7c64a5f419fcc36b53624e1c8d537a54a2f24f4185fd82c6ece568a5767fd2b1ddf48274e6fbe00f15bc668b73eb9d85a3f4ea17e8f303f7d0b2ba85a
+  data.tar.gz: 25af62fda64ddd54c860d6e0e63739cfe6e45618d1e7a510833b28cf6db6e47df26fce7b8044ba44c8a6e96bb865d593c71b99862291fead0c36ebe361b67414

data/README.md

@@ -41,26 +41,224 @@ end
 
 Once you've got it installed, you're good to go!
 
-TODO:
-- Expand on show action
-- - respond_with_resource
-  - explanation of side-loading
-- Expand on index action
-- - accessible and public records (required)
-- - default page size
-  - From, to, per, since, until, timeframe_for parameters
-  - Toggling pagination / timeframing
-  - Customizing the serializer options
-- Expand on create / update action
-  - create_action, update_action overriding
-  - respond_with_resource
-- Expand on destroy action [destroy_action]
-  - destroy_action overriding
-- Explain the respond_with_errors behaviour
+#### Some things to know about Snorlax:
+
+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.
+
+#### The show action
+
+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.
+
+```
+class TaurosController < Snorlax::Base
+  def load_resource
+    SafariZone.find(params[:id])
+  end
+end
+```
+
+NB: This would be a great place to ensure that the current user is allowed to view the requested resource.
+
+#### The index action
+
+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.
+
+```
+class StaryusController < Snorlax::Base
+  def public_records
+    Staryu.visible_to_public
+  end
+
+  def visible_records
+    current_user.staryus
+  end
+end
+```
+If these are the same, you may override the `accessible_records` method instead
+
+```
+class StarmiesController < Snorlax::Base
+  def accessible_records
+    Starmie.all
+  end
+end
+```
+
+The default index action look like this:
+
+```
+def index
+  instantiate_collection
+  respond_with_collection
+end
+```
+
+but there are many options to customize it.
+
+##### Paging the index action
+
+A Snorlax controller can accept `from` and `per` parameters for paging. For example,
+
+```
+/api/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.
+
+```
+class WobbuffetsController < Snorlax::Base
+  def default_page_size
+    25
+  end
+end
+```
+
+##### Timeframing the index action
+
+A Snorlax controller can accept `since` and `until` parameters for timeframing. The date it looks for defaults to `created_at`. For example,
+
+```
+/api/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,
+
+```
+/api/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.
+
+##### Overriding the timeframing or pagination options
+
+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.
+
+```
+class SquirtlesController < Snorlax::Base
+  def all_squirtles
+    instantiate_collection paginate_collection: false, timeframe_collection: false
+    respond_with_collection
+  end
+end
+```
+
+##### Custom filtering on the index action
+
+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,
+
+```
+class ChanseysController < Snorlax::Base
+  def sleeping
+    instantiate_collection { |collection| collection.where(sleeping: true) }
+    respond_with_collection
+  end
+end
+```
+
+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!)
+
+##### Customizing the serializer options
+
+By default, Snorlax will find a serializer based on the controller name, and serialize out your collection of records with a root.
+
+##### To override serializer and root for all actions in the controller
+
+You can override the serializer being used or the serializer root across the controller by defining a `resource_serializer` or `serializer_root` method, respectively:
+```
+class DittosController < Snorlax::Base
+  def resource_serializer
+    PokemonSerializer
+  end
+
+  def serializer_root
+    :pokemon
+  end
+end
+```
+
+This will result is JSON like this:
+```
+{ pokemon: [{ pokemon_serializer_field_a: 'valueA', pokemon_serializer_field_b: 'valueB' }] }
+```
+
+##### To override serializer and root for a single action
+
+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)
+
+```
+class DittosController < Snorlax::Base
+  def index
+    instantiate_collection
+    respond_with_collection serializer: PokemonSerializer, root: :pokemon, scope: { is_ditto: true }
+  end
+end
+```
+
+#### The create / update actions
+
+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:
+
+```
+def create
+  instantiate_resource
+  create_action
+  respond_with_resource
+end
+
+def create_action
+  resource.save
+end
+```
+
+##### Overriding the action command
+
+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)
+
+```
+def MewtwosController < Snorlax::Base
+  def create_action
+    Science.faff_about(resource_params)
+  end
+end
+```
+
+(NB: this is a good opportunity to make sure that the current user has permission to modify the record.)
+
+##### Overriding the resource serialization
+
+`respond_with_resource` accepts the same parameters as respond_with_collection, to allow for single-action customization of the json response.
+
+```
+def MewtwosController < Snorlax::Base
+  def create
+    instantiate_resource
+    create_action
+    respond_with_resource { serializer: LegendarySerializer, root: 'legendary_pokemon' }
+  end
+end
+```
+
+##### If there are errors on the object
+
+TODO: explain the respond_with_errors behaviour
 
 ## Contributing
 
-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](contributor-covenant.org) code of conduct.
+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](http://contributor-covenant.org) code of conduct.
 
 ## License
 

data/app/controllers/snorlax/base.rb

@@ -140,7 +140,7 @@ module Snorlax
           "#{resource_name}_serializer".camelize.constantize
         end
 
-        def respond_with_resource(scope: {}, serializer: resource_serializer, root: serializer_root)
+        def respond_with_resource(scope: default_scope, serializer: resource_serializer, root: serializer_root)
           if resource.errors.empty?
             respond_with_collection(resources: [resource], scope: scope, serializer: serializer, root: root)
           else
@@ -148,7 +148,7 @@ module Snorlax
           end
         end
 
-        def respond_with_collection(resources: collection, scope: {}, serializer: resource_serializer, root: serializer_root)
+        def respond_with_collection(resources: collection, scope: default_scope, serializer: resource_serializer, root: serializer_root)
           render json: resources, scope: scope, each_serializer: serializer, root: root
         end
 
@@ -163,6 +163,10 @@ module Snorlax
         def serializer_root
           controller_name
         end
+
+        def default_scope
+          {}
+        end
       end
     end
 

data/lib/snorlax/version.rb

@@ -1,3 +1,3 @@
 module Snorlax
-  VERSION = "0.1.1"
+  VERSION = "0.1.2"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: snorlax
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - James Kiesel (gdpelican)
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2015-08-07 00:00:00.000000000 Z
+date: 2015-08-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails