restful_json 3.0.1 → 3.1.0

data/README.md

@@ -5,7 +5,13 @@ Develop declarative, featureful JSON RESTful-ish service controllers to use with
 
 Should work with Rails 3.1+ and Rails 4. Feel free to submit issues and/or do a pull requests if you run into anything.
 
-Uses Adam Hawkin's [permitter][permitter] code which uses [strong_parameters][strong_parameters] and encourages use of [active_model_serializers][active_model_serializers].
+For the JSON response, you can either use [active_model_serializers][active_model_serializers], JBuilder, and perhaps others we haven't tested for control over the JSON response format. For active_model_serializers, it also provides the serialize_action class method in the controller to specify custom serializers (assuming you are using a later version of active_model_serializers that works with respond_with). For JBuilder, you can set render_enabled in the config to false.
+
+For the incoming JSON, it uses Adam Hawkin's [permitter][permitter] code which uses [strong_parameters][strong_parameters] and [cancan][cancan]. Permitters are an object-oriented way of defining what is permitted in the incoming JSON.
+
+An example app using restful_json with AngularJS is [employee-training-tracker][employee-training-tracker], featured in [Built with AngularJS][built_with_angularjs].
+
+The goal of restful_json is to reduce service controller code in an intuitive way, not to be a be-all DSL. The intent is for there to be no "restful_json way". It is currently opinionated about use of Cancan, strong_parameters, etc. because twinturbo [permitter][permitter] strategy uses those, but you can cut the ties via a pull request if you'd like.
 
 ### Installation
 
@@ -17,7 +23,26 @@ and:
 
     bundle install
 
-You need to setup [cancan][cancan]. Here are the basics:
+### Dependencies
+
+#### Rails
+
+Need at least Rails 3.1.0, but supports 3.1.x, 3.2.x, and 4+.
+
+Go with whatever you have in your Gemfile, e.g.:
+
+    gem 'rails', '3.2.11'
+
+If you don't want all of Rails (probably not the case), you at least need actionpack and activerecord:
+
+    gem 'actionpack', '> 3.1.0'
+    gem 'activerecord', '> 3.1.0'
+
+#### Cancan
+
+To use [cancan][cancan], in your Gemfile, add:
+
+    gem 'cancan', '~> 1.6.7'
 
 In your `app/controllers/application_controller.rb` or in your service controllers, make sure `current_user` is set:
 
@@ -41,31 +66,68 @@ In `app/models/ability.rb`, setup a basic cancan ability. Just for testing we'll
       end
     end
 
-### Responders
+#### Strong Parameters
+
+To use [strong_parameters][strong_parameters], in your Gemfile, add:
 
-If you plan to use responders outside of json with restful_json, you may want to formally install it, for flash messages, etc.:
+    gem 'strong_parameters', '~> 0.1.3'
 
-    gem install responders
+If you're using Rails 3.1.x/3.2.x and you want to disable the default whitelisting that occurs in later versions of Rails because you are going to use Strong Parameters, change the config.active_record.whitelist_attributes property in your `config/application.rb`:
 
-Add this to your Gemfile and bundle install:
+    config.active_record.whitelist_attributes = false
 
-    gem 'responders'
+This will allow you to remove / not have to use attr_accessible and do mass assignment inside your code and tests. Instead you will put this information into your permitters.
 
-And do:
+Note that restful_json automatically includes `ActiveModel::ForbiddenAttributesProtection` on all models, as is done in Rails 4.
 
-    rails generate responders:install
+#### JSON Response Generators
 
-### Strong Parameters
+##### ActiveModel Serializers
 
-If you want to now disable the default whitelisting that occurs in later versions of Rails, change the config.active_record.whitelist_attributes property in your `config/application.rb`:
+If you want to use [ActiveModel Serializers][[active_model_serializers], use:
 
-    config.active_record.whitelist_attributes = false
+    gem 'active_model_serializers'
 
-This will allow you to remove / not have to use attr_accessible and do mass assignment inside your code and tests. Instead you will put this information into your permitters.
+Then create your serializers, e.g.:
+
+    /app/serializers/singular_model_name_serializer.rb
+
+Without having to do anything else, each restful_json controller will use `/app/serializers/singular_model_name_serializer.rb`, e.g. `/app/serializers/bar_serializer.rb` for the actions: index, show, new, create, update, destroy (not edit).
+
+If you want to define a different serializer another action, e.g. the index action so that a list of instances has a different JSON format:
+
+    serialize_action :index, with: BarsSerializer
+
+You can also use a specific format for multiple actions:
+
+    serialize_action :index, :my_other_list_action, with: BarsSerializer
+
+The built-in actions that support custom serializers (you can add more) are: index, show, new, create, update, destroy, and any action you automatically have created via using the restful_json `query_for` method (keep reading!).
+
+##### JBuilder
+
+If you want to use JBuilder instead to render, first:
 
-Note that restful_json automatically includes `ActiveModel::ForbiddenAttributesProtection` on all models as will be done in Rails 4.
+    gem 'jbuilder'
 
-### Configuration
+If you want to enable JBuilder for all restful_json services, you need to disable all renders and respond_withs in the controller:
+
+    RestfulJson.render_enabled = false
+
+Or you can also just enable/disable rendering in a controller via setting `self.render_enabled`:
+
+    self.render_enabled = false
+
+Then make sure you add a JBuilder view for each action you require. Although all may not be relevant, we support: index, show, new, edit, create, update, destroy. Maybe you'd create:
+
+    /app/views/plural_name_of_model/index.json.jbuilder
+    /app/views/plural_name_of_model/show.json.jbuilder
+    /app/views/plural_name_of_model/create.json.jbuilder
+    /app/views/plural_name_of_model/update.json.jbuilder
+
+See [Railscast #320][railscast320] for examples.
+
+### App-level Configuration
 
 At the bottom of `config/environment.rb`, you can set config items one at a time like:
 
@@ -74,67 +136,149 @@ At the bottom of `config/environment.rb`, you can set config items one at a time
 or in bulk like:
 
     RestfulJson.configure do
-      self.can_filter_by_default_using = [:eq] # default for :using in can_filter_by
-      self.debug = false # to output debugging info during request handling
-      self.filter_split = ',' # delimiter for values in request parameter values
-      self.formats = :json, :html # equivalent to specifying respond_to :json, :html in the controller, and can be overriden in the controller. Note that by default responders gem sets respond_to :html in application_controller.rb.
-      self.number_of_records_in_a_page = 15 # default number of records to return if using the page request function
-      self.predicate_prefix = '!' # delimiter for ARel predicate in the request parameter name
-      self.return_resource = false # if true, will render resource and HTTP 201 for post/create or resource and HTTP 200 for put/update
+      
+      # default for :using in can_filter_by
+      self.can_filter_by_default_using = [:eq]
+      
+      # to output debugging info during request handling
+      self.debug = false
+      
+      # delimiter for values in request parameter values
+      self.filter_split = ','
+      
+      # equivalent to specifying respond_to :json, :html in the controller, and can be overriden in the controller. Note that by default responders gem sets respond_to :html in application_controller.rb.
+      self.formats = :json, :html
+      
+      # default number of records to return if using the page request function
+      self.number_of_records_in_a_page = 15
+      
+      # delimiter for ARel predicate in the request parameter name
+      self.predicate_prefix = '!'
+      
+      # if true, will render resource and HTTP 201 for post/create or resource and HTTP 200 for put/update
+      self.return_resource = false 
+
     end
 
-#### Advanced Configuration
+### Controller-specific Configuration
+
+In the controller, you can set a variety of class attributes with `self.something = ...` in the body of your controller.
+
+All of the app-level configuration parameters are configurable at the controller level:
+
+      self.can_filter_by_default_using = [:eq]
+      self.debug = false
+      self.filter_split = ','
+      self.formats = :json, :html
+      self.number_of_records_in_a_page = 15
+      self.predicate_prefix = '!'
+      self.return_resource = false 
+
+In addition there are some that are controller-only...
+
+If you don't use the standard controller naming convention, you can define this in the controller:
 
-In the controller, you can set a variety of class attributes with `self.something = ...` in the body of your controller to set model class, variable names, messages, etc. Take a look at the class_attribute definitions in `lib/restful_json/controller.rb`.
+        self.model_class = YourModel
+
+If it doesn't handle the other forms well, you can explicitly define the singular/plural names:
+
+        self.model_singular_name = 'your_model'
+        self.model_plural_name = 'your_models'
+
+These are used for *_url method definitions, to set instance variables like `@foobar` and `@foobars` dynamically, etc.
+
+Other class attributes are available for setting/overriding, but they are all set by the other class methods defined in the next section.
 
 ### Usage
 
-By using `acts_as_restful_json` you have a configurable generic Rails 3.1+ controller that does the index, show, create, and update and other custom actions easily for you.
+By using `acts_as_restful_json`, you have a configurable generic Rails 3.1+/4+ controller that does the index, show, create, and update and other custom actions easily for you.
 
-Everything is well-declared and concise:
+Everything is well-declared and fairly concise.
 
-    class FoobarsController < ApplicationController  
+You can have something as simple as:
+
+    class FoobarsController < ApplicationController
+      
       acts_as_restful_json
+
+    end
+
+which would use the restful_json configuration and the controller's classname for the service definition.
+
+Or you can define more bells and whistles (read on to see what these do...):
+
+    class FoobarsController < ApplicationController
+      
+      acts_as_restful_json
+      
       query_for :index, is: ->(t,q) {q.joins(:apples, :pears).where(apples: {color: 'green'}).where(pears: {color: 'green'})}
+      
       # args sent to can_filter_by are the request parameter name(s)
-      can_filter_by :foo_id # implies using: [:eq] because RestfulJson.can_filter_by_default_using = [:eq]
-      can_filter_by :foo_date, :bar_date, using: [:lt, :eq, :gt], with_default: Time.now # can specify multiple predicates and optionally a default value
+      
+      # implies using: [:eq] because RestfulJson.can_filter_by_default_using = [:eq]
+      can_filter_by :foo_id
+      
+      # can specify multiple predicates and optionally a default value
+      can_filter_by :foo_date, :bar_date, using: [:lt, :eq, :gt], with_default: Time.now
+      
       can_filter_by :a_request_param_name, with_query: ->(t,q,param_value) {q.joins(:some_assoc).where(:some_assocs_table_name=>{some_attr: param_value})}
+      
       can_filter_by :and_another, through: [:some_attribute_on_this_model]
+      
       can_filter_by :one_more, through: [:some_association, :some_attribute_on_some_association_model]
+      
       can_filter_by :and_one_more, through: [:my_assoc, :my_assocs_assoc, :my_assocs_assocs_assoc, :an_attribute_on_my_assocs_assocs_assoc]
+      
       supports_functions :count, :uniq, :take, :skip, :page, :page_count
+      
       order_by {:foo_date => :asc}, :foo_color, {:bar_date => :desc} # an ordered array of hashes, assumes :asc if not a hash
-      respond_to :json, :html # specify if you want more than :json. It dynamically sets model variables with the right names, e.g. @foobar and @foobars.
+      
+      # comma-delimited if you want more than :json, e.g. :json, :html
+      respond_to :json, :html
+      
     end
 
-`can_filter_by` without an option means you can send in that request param (via routing or directly, just like normal in Rails) and it will use that in the ARel query (safe from SQL injection and only letting you do what you tell it). `:using` means you can use those [ARel][arel] predicates for filtering. For a full list of available ones do:
+#### Default Filtering by Attribute(s)
 
-    rails c
-    Arel::Predications.public_instance_methods.sort
+First, declare in the controller:
 
-at time of writing these were:
+    can_filter_by :foo_id
 
-    [:does_not_match, :does_not_match_all, :does_not_match_any, :eq, :eq_all, :eq_any, :gt, :gt_all, :gt_any, :gteq, :gteq_all, :gteq_any, :in, :in_all, :in_any, :lt, :lt_all, :lt_any, :lteq, :lteq_all, :lteq_any, :matches, :matches_all, :matches_any, :not_eq, :not_eq_all, :not_eq_any, :not_in, :not_in_all, :not_in_any]
+If `RestfulJson.can_filter_by_default_using = [:eq]` as it is by default, then you can now get Foobars with a foo_id of '1':
 
-`supports_functions` lets you do other [ARel][arel] functions. `:uniq`, `:skip`, `:take`, and `:count`.
+    http://localhost:3000/foobars?foo_id=1
 
-`can_filter_by` can also specify a `:with_query` to provide a lambda that takes the request parameter in when it is provided by the request.
+`can_filter_by` without an option means you can send in that request param (via routing or directly, just like normal in Rails) and it will use that in the ARel query (safe from SQL injection and only letting you do what you tell it). `:using` means you can use those [ARel][arel] predicates for filtering. If you do `Arel::Predications.public_instance_methods.sort` in Rails console, you can see a list of the available predicates. So, you could get crazy with:
 
-And `can_filter_by` can also specify a `:through` to provide an easy way to inner join through a bunch models (using ActiveRecord relations) by specifying 0-to-many association names to go "through" to the final argument which is the attribute name on the last model, e.g. the two following are equivalent:
+    can_filter_by :does_not_match, :does_not_match_all, :does_not_match_any, :eq, :eq_all, :eq_any, :gt, :gt_all, :gt_any, :gteq, :gteq_all, :gteq_any, :in, :in_all, :in_any, :lt, :lt_all, :lt_any, :lteq, :lteq_all, :lteq_any, :matches, :matches_all, :matches_any, :not_eq, :not_eq_all, :not_eq_any, :not_in, :not_in_all, :not_in_any
+
+`can_filter_by` can also specify a `:with_query` to provide a lambda that takes the request parameter in when it is provided by the request.
 
     can_filter_by :a_request_param_name, with_query: ->(t,q,param_value) {q.joins(:some_assoc).where(:some_assocs_table_name=>{some_attr: param_value})}
-    can_filter_by :a_request_param_name, through: [:some_assoc, :some_attr] # much easier, but not as flexible as a lambda
 
-#### Default Filter by Attribute(s)
+And `can_filter_by` can specify a `:through` to provide an easy way to inner join through a bunch of models using ActiveRecord relations, by specifying 0-to-many association names to go "through" to the final argument, which is the attribute name on the last model. The following is equivalent to the last query:
 
-First, declare in the controller:
+    can_filter_by :a_request_param_name, through: [:some_assoc, :some_attr]
 
-    can_filter_by :foo_id
+Let's say you are in MagicalValleyController, and the MagicalValley model `has many :magical_unicorns`. The MagicalUnicorn model has an attribute called `name`. You want to return MagicalValleys that are associated with all of the MagicalUnicorns named 'Rainbow'. You could do either:
 
-If `RestfulJson.can_filter_by_default_using = [:eq]` as it is by default, then you can now get Foobars with a foo_id of '1':
+    can_filter_by :magical_unicorn_name, with_query: ->(t,q,param_value) {q.joins(:magical_unicorns).where(:magical_unicorns=>{name: param_value})}
 
-    http://localhost:3000/foobars?foo_id=1
+or:
+
+    can_filter_by :magical_unicorn_name, through: [:magical_unicorns, :name]
+
+and you can then use this:
+
+    http://localhost:3000/magical_valleys?magical_unicorn_name=Rainbow
+
+or if a MagicalUnicorn `has_many :friends` and a MagicalUnicorn's friend has a name attribute:
+
+    can_filter_by :magical_unicorn_friend_name, through: [:magical_unicorns, :friends, :name]
+
+and use this to get valleys associated with unicorns who in turn have a friend named Oscar:
+
+    http://localhost:3000/magical_valleys?magical_unicorn_friend_name=Oscar
 
 #### Other Filters by Attribute(s)
 
@@ -150,17 +294,23 @@ Multiple values are separated by `filter_split` (configurable):
 
     http://localhost:3000/foobars?seen_on!eq_any=2012-08-08,2012-09-09
 
-#### Unique (DISTINCT)
+#### Supported Functions
+
+##### Declaring
+
+`supports_functions` lets you allow the [ARel][arel] functions: `:uniq`, `:skip`, `:take`, and/or `:count`.
+
+##### Unique (DISTINCT)
 
 First, declare in the controller:
 
     supports_functions :uniq
 
-To return a simple unique view of a model, combine use of an active_model_serializer that returns just the attribute you want along with the uniq param, e.g. to return unique/distinct colors of foobars you'd have a serializer to just return the color and then use:
+To return a simple unique view of a model, combine use of an [ActiveModel Serializer][active_model_serializers] that returns just the attribute you want along with the uniq param, e.g. to return unique/distinct colors of foobars you'd have a serializer to just return the color and then use:
 
     http://localhost:3000/foobars?uniq=
 
-#### Count
+##### Count
 
 First, declare in the controller:
 
@@ -170,7 +320,7 @@ This is another filter that can be used with the others, but instead of returnin
 
     http://localhost:3000/foobars?count=
 
-#### Paging
+##### Paging
 
 In controller make sure these are included:
 
@@ -198,7 +348,7 @@ To set page size at controller level:
 
 For a better idea of how this works on the backend, look at [ARel][arel]'s skip and take, or see Variable Paging.
 
-##### Skip and Take (OFFSET and LIMIT)
+###### Skip and Take (OFFSET and LIMIT)
 
 In controller make sure these are included:
 
@@ -212,8 +362,6 @@ To limit the number of rows returned, use 'take'. It is called take, because tak
 
     http://localhost:3000/foobars.json?take=5
 
-##### Variable Paging
-
 Combine skip and take for manual completely customized paging.
 
 Get the first page of 15 results:
@@ -257,7 +405,7 @@ or use the `->` Ruby 1.9 lambda stab operator. You can also filter out items tha
       .where(pears: {color: 'green'})
     }
 
-##### Custom Actions
+##### Define Custom Actions with Custom Queries
 
 `query_for` also will `alias_method (some action), :index` anything other than `:index`, so you can easily create custom non-RESTful action methods:
 
@@ -267,6 +415,8 @@ or use the `->` Ruby 1.9 lambda stab operator. You can also filter out items tha
 
 Note that it is a proc so you can really do whatever you want with it and will have access to other things in the environment or can call another method, etc.
 
+You are still working with regular controllers here, so add or override methods if you want more!
+
 ### Routing
 
 Respects regular and nested Rails resourceful routing and controller namespacing, e.g. in `config/routes.rb`:
@@ -279,6 +429,113 @@ Respects regular and nested Rails resourceful routing and controller namespacing
       end
     end
 
+### Experimental Usage
+
+#### Rails-api
+
+If you want to try out [rails-api][rails-api], maybe use:
+
+    gem 'rails-api', '~> 0.0.3'
+
+    class ServiceController < ActionController::API
+      
+      include AbstractController::Translation
+      include ActionController::HttpAuthentication::Basic::ControllerMethods
+      include AbstractController::Layouts
+      include ActionController::MimeResponds
+      include ActionController::Cookies
+      include ActionController::ParamsWrapper
+      acts_as_restful_json
+      
+      def current_user
+        User.new
+      end
+      
+    end
+
+Note that in `/config/initializers/wrap_parameters.rb` you might need to add `include ActionController::ParamsWrapper` prior to the `wrap_parameters` call. For example, for unwrapped JSON, it would look like:
+
+    ActiveSupport.on_load(:action_controller) do
+      # without include of ParamsWrapper, will get undefined method `wrap_parameters' for ActionController::API:Class (NoMethodError)
+      include ActionController::ParamsWrapper
+      # in this case it's expecting unwrapped params, but we could maybe use wrap_parameters format: [:json]
+      wrap_parameters format: []
+    end
+
+    # Disable root element in JSON by default.
+    ActiveSupport.on_load(:active_record) do
+      self.include_root_in_json = false
+    end
+
+#### Customing the Default Behavior
+
+In `app/controllers/able_to_mark_on_destroy.rb`, you could have:
+
+    module AbleToMarkOnDestroy
+      extend ActiveSupport::Concern
+
+      included do
+        # things you would put in the body of the class        
+        class_attribute :deleted_status_column, instance_writer: true
+      end
+
+      # no need to define class methods for this example, but this is where you'd do it
+      #module ClassMethods
+      #end
+
+      # instance methods from here on out...
+
+      # Note: overriding destroy in restful_json to support marking deleted_status_column with 'deleted'
+      def destroy
+        # to_s for vulnerabilities similar to CVE-2013-1854 in older Rails...
+        @value = @model_class.find(params[:id].to_s)
+        unless @value.nil? || !self.deleted_status_column
+          @value.update_attributes!({self.deleted_status_column.to_sym => 'deleted'})
+        else
+          @value.destroy
+        end
+      
+        instance_variable_set(@model_at_singular_name_sym, @value)
+
+        if self.render_enabled
+          # you could take out the custom_action_serializer support if you aren't using
+          custom_action_serializer = self.action_to_serializer[params[:action].to_s]
+          
+          if !@value.nil? && RestfulJson.return_resource
+            respond_with(@value) do |format|
+              format.json do
+                # for errors added in before_destroy validation or in update_attributes
+                if @value.errors.empty?
+                  render custom_action_serializer ? {json: @value, status: :ok, serializer: custom_action_serializer} : {json: @value, status: :ok}
+                else
+                  render custom_action_serializer ? {json: {errors: @value.errors}, status: :unprocessable_entity, serializer: custom_action_serializer} : {json: {errors: @value.errors}, status: :unprocessable_entity}
+                end
+              end
+            end
+          else
+            respond_with @value, custom_action_serializer ? {serializer: custom_action_serializer} : {}
+          end
+        end
+      end
+    end
+
+Then in your controller:
+
+    acts_as_restful_json
+    include AbleToMarkOnDestroy
+    
+    self.deleted_status_column = :foo_deleted
+
+And when you do a RESTful call to destroy id 123 via a DELETE:
+
+    http://localhost:3000/foobars/123
+
+Instead of deleting the DB row, the 'foobars' table row's column 'foo_deleted' would be set to 'deleted'.
+
+### Thanks!
+
+Without our users, where would we be? Feedback, bug reports, and code/documentation contributions are always welcome!
+
 ### Contributors
 
 * Gary Weaver (https://github.com/garysweaver)
@@ -288,6 +545,8 @@ Respects regular and nested Rails resourceful routing and controller namespacing
 
 Copyright (c) 2012 Gary S. Weaver, released under the [MIT license][lic].
 
+[employee-training-tracker]: https://github.com/FineLinePrototyping/employee-training-tracker
+[built_with_angularjs]: http://builtwith.angularjs.org/
 [permitter]: http://broadcastingadam.com/2012/07/parameter_authorization_in_rails_apis/
 [cancan]: https://github.com/ryanb/cancan
 [strong_parameters]: https://github.com/rails/strong_parameters
@@ -296,4 +555,6 @@ Copyright (c) 2012 Gary S. Weaver, released under the [MIT license][lic].
 [devise]: https://github.com/plataformatec/devise
 [arel]: https://github.com/rails/arel
 [ar]: http://api.rubyonrails.org/classes/ActiveRecord/Relation.html
+[rails-api]: https://github.com/rails-api/rails-api
+[railscast320]: http://railscasts.com/episodes/320-jbuilder
 [lic]: http://github.com/rubyservices/restful_json/blob/master/LICENSE

data/lib/restful_json/config.rb

@@ -6,7 +6,8 @@ module RestfulJson
     :formats,
     :number_of_records_in_a_page,
     :predicate_prefix,
-    :return_resource
+    :return_resource,
+    :render_enabled
   ]
   
   class << self
@@ -24,4 +25,5 @@ RestfulJson.configure do
   self.number_of_records_in_a_page = 15
   self.predicate_prefix = '!'
   self.return_resource = false
+  self.render_enabled = true
 end

data/lib/restful_json/controller.rb

@@ -40,6 +40,7 @@ module RestfulJson
         class_attribute :action_to_query, instance_writer: true
         class_attribute :param_to_query, instance_writer: true
         class_attribute :param_to_through, instance_writer: true
+        class_attribute :action_to_serializer, instance_writer: true
 
         # use values from config
         # debug uses RestfulJson.debug? because until this is done no local debug class attribute exists to check
@@ -54,6 +55,7 @@ module RestfulJson
         self.action_to_query ||= {}
         self.param_to_query ||= {}
         self.param_to_through ||= {}
+        self.action_to_serializer ||= {}
       end
 
       module ClassMethods
@@ -134,6 +136,21 @@ module RestfulJson
         def order_by(args)
           self.ordered_by = (Array.wrap(self.ordered_by) + Array.wrap(args)).flatten.compact.collect {|item|item.is_a?(Hash) ? item : {item.to_sym => :asc}}
         end
+
+        # Associate a non-standard ActiveModel Serializer for one or more actions, e.g.
+        #    serialize_action :index, with: FoosSerializer
+        # or
+        #    serialize_action :index, :some_custom_action, with: FoosSerializer
+        def serialize_action(*args)
+          options = args.extract_options!
+          args.each do |an_action|
+            if options[:with]
+              self.action_to_serializer[an_action.to_s] = options[:with]
+            else
+              raise "#{self.class.name} must supply an :with option with serialize_action #{an_action.inspect}"
+            end
+          end
+        end
       end
 
       # In initialize we:
@@ -268,7 +285,11 @@ module RestfulJson
 
         @value = value
         instance_variable_set(@model_at_plural_name_sym, @value)
-        respond_with @value
+        
+        if self.render_enabled  
+          custom_action_serializer = self.action_to_serializer[params[:action].to_s]
+          respond_with @value, custom_action_serializer ? {serializer: custom_action_serializer} : {}
+        end
       end
 
       # The controller's show (get) method to return a resource.
@@ -276,13 +297,21 @@ module RestfulJson
         # to_s as safety measure for vulnerabilities similar to CVE-2013-1854
         @value = @model_class.find(params[:id].to_s)
         instance_variable_set(@model_at_singular_name_sym, @value)
-        respond_with @value
+        
+        if self.render_enabled  
+          custom_action_serializer = self.action_to_serializer[params[:action].to_s]
+          respond_with @value, custom_action_serializer ? {serializer: custom_action_serializer} : {}
+        end
       end
 
       # The controller's new method (e.g. used for new record in html format).
       def new
         @value = @model_class.new
-        respond_with @value
+
+        if self.render_enabled  
+          custom_action_serializer = self.action_to_serializer[params[:action].to_s]
+          respond_with @value, custom_action_serializer ? {serializer: custom_action_serializer} : {}
+        end
       end
 
       # The controller's edit method (e.g. used for edit record in html format).
@@ -298,18 +327,27 @@ module RestfulJson
         @value = @model_class.new(permitted_params)
         @value.save
         instance_variable_set(@model_at_singular_name_sym, @value)
-        if RestfulJson.return_resource
-          respond_with(@value) do |format|
-            format.json do
-              if @value.errors.empty?
-                render json: @value, status: :created
-              else
-                render json: {errors: @value.errors}, status: :unprocessable_entity
+
+        if self.render_enabled  
+          custom_action_serializer = self.action_to_serializer[params[:action].to_s]
+          respond_with @value, custom_action_serializer ? {serializer: custom_action_serializer} : {}
+        end
+
+        if self.render_enabled
+          custom_action_serializer = self.action_to_serializer[params[:action].to_s]
+          if !@value.nil? && RestfulJson.return_resource
+            respond_with(@value) do |format|
+              format.json do
+                if @value.errors.empty?
+                  render custom_action_serializer ? {json: @value, status: :created, serializer: custom_action_serializer} : {json: @value, status: :created}
+                else
+                  render custom_action_serializer ? {json: {errors: @value.errors}, status: :unprocessable_entity, serializer: custom_action_serializer} : {json: {errors: @value.errors}, status: :unprocessable_entity}
+                end
               end
             end
+          else
+            respond_with @value, custom_action_serializer ? {serializer: custom_action_serializer} : {}
           end
-        else
-          respond_with @value
         end
       end
 
@@ -320,18 +358,22 @@ module RestfulJson
         @value = @model_class.find(params[:id].to_s)
         @value.update_attributes(permitted_params)
         instance_variable_set(@model_at_singular_name_sym, @value)
-        if RestfulJson.return_resource
-          respond_with(@value) do |format|
-            format.json do
-              if @value.errors.empty?
-                render json: @value, status: :ok
-              else
-                render json: {errors: @value.errors}, status: :unprocessable_entity
+        
+        if self.render_enabled
+          custom_action_serializer = self.action_to_serializer[params[:action].to_s]
+          if !@value.nil? && RestfulJson.return_resource
+            respond_with(@value) do |format|
+              format.json do
+                if @value.errors.empty?
+                  render custom_action_serializer ? {json: @value, status: :ok, serializer: custom_action_serializer} : {json: @value, status: :ok}
+                else
+                  render custom_action_serializer ? {json: {errors: @value.errors}, status: :unprocessable_entity, serializer: custom_action_serializer} : {json: {errors: @value.errors}, status: :unprocessable_entity}
+                end
               end
             end
+          else
+            respond_with @value, custom_action_serializer ? {serializer: custom_action_serializer} : {}
           end
-        else
-          respond_with @value
         end
       end
 
@@ -341,7 +383,10 @@ module RestfulJson
         @value = @model_class.find(params[:id].to_s)
         @value.destroy
         instance_variable_set(@model_at_singular_name_sym, @value)
-        respond_with @value
+
+        if self.render_enabled
+          respond_with @value, custom_action_serializer ? {serializer: custom_action_serializer} : {}
+        end
       end
 
     end

data/lib/restful_json/version.rb

@@ -1,3 +1,3 @@
 module RestfulJson
-  VERSION = '3.0.1'
+  VERSION = '3.1.0'
 end

data/lib/twinturbo/application_permitter.rb

@@ -0,0 +1,93 @@
+# from Adam Hawkins's gist:
+# https://gist.github.com/3150306
+# http://www.broadcastingadam.com/2012/07/parameter_authorization_in_rails_apis/
+class ApplicationPermitter
+  class PermittedAttribute < Struct.new(:name, :options) ; end
+
+  delegate :authorize!, :to => :ability
+  class_attribute :permitted_attributes
+  self.permitted_attributes = []
+
+  class << self
+    def permit(*args)
+      options = args.extract_options!
+
+      args.each do |name|
+        self.permitted_attributes += [PermittedAttribute.new(name, options)]
+      end
+    end
+
+    def scope(name)
+      with_options :scope => name do |nested|
+        yield nested
+      end
+    end
+  end
+
+  def initialize(params, user, ability = nil)
+    @params, @user, @ability = params, user, ability
+  end
+
+  def permitted_params
+    authorize_params!
+    filtered_params
+  end
+
+  def resource_name
+    self.class.to_s.match(/(.+)Permitter/)[1].underscore.to_sym
+  end
+
+
+private
+
+  def authorize_params!
+    needing_authorization = permitted_attributes.select { |a| a.options[:authorize] }
+
+    needing_authorization.each do |attribute|
+      if attribute.options[:scope]
+        values = Array.wrap(filtered_params[attribute.options[:scope]]).collect do |hash|
+          hash[attribute.name]
+        end.compact
+      else
+        values = Array.wrap filtered_params[attribute.name]
+      end
+
+      klass = (attribute.options[:as].try(:to_s) || attribute.name.to_s.split(/(.+)_ids?/)[1]).classify.constantize
+
+      values.each do |record_id|
+        record = klass.find record_id
+        permission = attribute.options[:authorize].to_sym || :read
+        authorize! permission, record
+      end
+    end
+  end
+
+  def filtered_params
+    scopes = {}
+    unscoped_attributes = []
+
+    permitted_attributes.each do |attribute|
+      if attribute.options[:scope]
+        key = attribute.options[:scope]
+        scopes[key] ||= []
+        scopes[key] << attribute.name
+      else
+        unscoped_attributes << attribute.name
+      end
+    end
+
+    @filtered_params ||= params.require(resource_name).permit(*unscoped_attributes, scopes)
+  end
+
+  def params
+    @params
+  end
+
+  def user
+    @user
+  end
+
+  def ability
+    @ability ||= Ability.new user
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: restful_json
 version: !ruby/object:Gem::Version
-  version: 3.0.1
+  version: 3.1.0
   prerelease: 
 platform: ruby
 authors:
@@ -10,40 +10,8 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-03-19 00:00:00.000000000 Z
+date: 2013-03-22 00:00:00.000000000 Z
 dependencies:
-- !ruby/object:Gem::Dependency
-  name: rails-api
-  requirement: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: active_model_serializers
-  requirement: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
 - !ruby/object:Gem::Dependency
   name: actionpack
   requirement: !ruby/object:Gem::Requirement
@@ -51,7 +19,7 @@ dependencies:
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 3.1.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -59,7 +27,7 @@ dependencies:
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 3.1.0
 - !ruby/object:Gem::Dependency
   name: activerecord
   requirement: !ruby/object:Gem::Requirement
@@ -67,7 +35,7 @@ dependencies:
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 3.1.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -75,7 +43,7 @@ dependencies:
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 3.1.0
 - !ruby/object:Gem::Dependency
   name: cancan
   requirement: !ruby/object:Gem::Requirement
@@ -83,7 +51,7 @@ dependencies:
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 1.6.7
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -91,7 +59,7 @@ dependencies:
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 1.6.7
 - !ruby/object:Gem::Dependency
   name: strong_parameters
   requirement: !ruby/object:Gem::Requirement
@@ -99,7 +67,7 @@ dependencies:
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.1.3
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -107,7 +75,7 @@ dependencies:
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.1.3
 description: Develop declarative, featureful JSON RESTful-ish service controllers
   to use with modern Javascript MVC frameworks like AngularJS, Ember, etc. with much
   less code.
@@ -124,6 +92,7 @@ files:
 - lib/restful_json/railtie.rb
 - lib/restful_json/version.rb
 - lib/restful_json.rb
+- lib/twinturbo/application_permitter.rb
 - lib/twinturbo/controller.rb
 - Rakefile
 - README.md