api_helper 0.0.2 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ea6fee61c677b49c8f59a3cba0c0d7bcdfb570ef
-  data.tar.gz: 2f2a2f2960c5e406a9c2a5c8a52f813bd13adfad
+  metadata.gz: 326e1e9e2c1b9509990e1103a0d8f95da5be83a9
+  data.tar.gz: 4c9fd145828a49a586d8a4b7dee67fa177ea957c
 SHA512:
-  metadata.gz: f6fb52e869d6d29c3aabd48dc69f50a30d1a869b882a6416d6abeca01ebbfbbae56e9959a553bc54d9e38f1c08904c3dce3d068b5f18c3744202bc7a49ff23dc
-  data.tar.gz: 1b02bc8d125ce5c0091bb8c2a2fa8c3519eab5598d2a497b2f5cc814d78696b9f88e619b8533433d66eda6544234df71352d2b0ee33e6a1d8f35c1af7ff19363
+  metadata.gz: d14e69fb29488afe354b941fc4501ba92620936731673a2bc41274cf37f77bd4f2fbcf7e368e9dd8cc52e473a4b9b8ce1fd1b49391d59f6e638df0fac6452eda
+  data.tar.gz: f44a72e00cc934ad01194d0c20fa799f0fc6e232d26abced40f6a60b120b6942b66db0d3e21bfa90496ecc10e0b51b84833ad77727ebb2b85363dd1a5c7e5177

data/.gitignore

@@ -7,3 +7,4 @@
 /pkg/
 /spec/reports/
 /tmp/
+/gemfiles/*.gemfile.lock

data/.travis.yml

@@ -1,4 +1,10 @@
 language: ruby
 rvm:
+  - 2.0.0
   - 2.2.0
+gemfile:
+  - gemfiles/rails_4.1.0.gemfile
+  - gemfiles/rails_4.2.0.gemfile
+  - gemfiles/grape_0.10.0.gemfile
+  - gemfiles/grape_0.11.0.gemfile
 before_install: gem install bundler -v 1.10.2

data/Appraisals

@@ -0,0 +1,23 @@
+appraise 'rails-4.1.0' do
+  gemspec
+  gem 'rails', '4.1.0'
+  gem 'rspec-rails'
+end
+
+appraise 'rails-4.2.0' do
+  gemspec
+  gem 'rails', '4.2.0'
+  gem 'rspec-rails'
+end
+
+appraise 'grape-0.10.0' do
+  gemspec
+  gem 'grape', '0.10.0'
+  gem 'rack-test'
+end
+
+appraise 'grape-0.11.0' do
+  gemspec
+  gem 'grape', '0.11.0'
+  gem 'rack-test'
+end

data/README.md

@@ -1,4 +1,4 @@
-# APIHelper
+# APIHelper [![Gem Version](https://badge.fury.io/rb/api_helper.svg)](http://badge.fury.io/rb/api_helper) [![Build Status](https://travis-ci.org/Neson/api_helper.svg?branch=master)](https://travis-ci.org/Neson/api_helper) [![Docs Status](https://inch-ci.org/github/Neson/api_helper.svg?branch=master)](https://inch-ci.org/github/Neson/api_helper)
 
 Helpers for creating standard RESTful API for Rails or Grape with Active Record.
 
@@ -8,7 +8,7 @@ Helpers for creating standard RESTful API for Rails or Grape with Active Record.
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'APIHelper'
+gem 'api_helper'
 ```
 
 And then execute:
@@ -17,7 +17,7 @@ And then execute:
 
 Or install it yourself as:
 
-    $ gem install APIHelper
+    $ gem install api_helper
 
 
 ## API Standards
@@ -62,7 +62,7 @@ PostsController < ApplicationController
 end
 ```
 
-Further usage of each helper can be found in the docs.
+Further usage of each helper can be found in the [docs](http://www.rubydoc.info/github/Neson/api_helper/master/APIHelper).
 
 ### Grape
 
@@ -79,16 +79,16 @@ class PostsAPI < Grape::API
 end
 ```
 
-Further usage of each helper can be found in the docs.
+Further usage of each helper can be found in the [docs](http://www.rubydoc.info/github/Neson/api_helper/master/APIHelper).
 
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake rspec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `appraisal rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
 To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/Neson/APIHelper.
+Bug reports and pull requests are welcome on GitHub at https://github.com/Neson/api_helper.

data/api_helper.gemspec

@@ -20,7 +20,11 @@ Gem::Specification.new do |spec|
 
   spec.add_development_dependency "bundler"
   spec.add_development_dependency "rake"
+  spec.add_development_dependency "appraisal"
   spec.add_development_dependency "rspec"
+  spec.add_development_dependency "byebug"
+  spec.add_development_dependency "activerecord"
+  spec.add_development_dependency "sqlite3"
 
   spec.add_dependency "activesupport", ">= 3"
 end

data/gemfiles/grape_0.10.0.gemfile

@@ -0,0 +1,8 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "grape", "0.10.0"
+gem "rack-test"
+
+gemspec :path => "../"

data/gemfiles/grape_0.11.0.gemfile

@@ -0,0 +1,8 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "grape", "0.11.0"
+gem "rack-test"
+
+gemspec :path => "../"

data/gemfiles/rails_4.0.0.gemfile

@@ -0,0 +1,8 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "rails", "4.0.0"
+gem "rspec-rails"
+
+gemspec :path => "../"

data/gemfiles/rails_4.1.0.gemfile

@@ -0,0 +1,8 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "rails", "4.1.0"
+gem "rspec-rails"
+
+gemspec :path => "../"

data/gemfiles/rails_4.1.8.gemfile

@@ -0,0 +1,8 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "rails", "4.2.0"
+gem "rspec-rails"
+
+gemspec :path => "../"

data/gemfiles/rails_4.2.0.gemfile

@@ -0,0 +1,8 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "rails", "4.2.0"
+gem "rspec-rails"
+
+gemspec :path => "../"

data/lib/api_helper/fieldsettable.rb

@@ -1,31 +1,34 @@
 require 'active_support'
+require 'active_support/core_ext/object/blank'
 
-# = Helper To Make Resource APIs Fieldsettable
+# = Fieldsettable
 #
-# By making an API fieldsettable, you let API callers to choose the fields they
-# wanted to be returned with query parameters. This is really useful for making
-# API calls more efficient and fast.
+# By making an API fieldsettable, you enables the ability for API clients to
+# choose the returned fields of resources with URL query parameters. This is
+# really useful for optimizing requests, making API calls more efficient and
+# fast.
 #
 # This design made references to the rules of <em>Sparse Fieldsets</em> in
 # <em>JSON API</em>:
 # http://jsonapi.org/format/#fetching-sparse-fieldsets
 #
-# A client can request that an API endpoint return only specific fields in the
-# response by including a +fields+ parameter, which is a comma-separated (",")
-# list that refers to the name(s) of the fields to be returned.
+# A client can request to get only specific fields in the response by using
+# the +fields+ parameter, which is expected to be a comma-separated (",") list
+# that refers to the name(s) of the fields to be returned.
 #
 #   GET /users?fields=id,name,avatar_url
 #
-# This functionality may also support requests specifying multiple fieldsets
-# for several objects at a time (e.g. another object included in an field of
-# another object) with <tt>fields[object_type]</tt> parameters.
+# This functionality may also support requests passing in multiple fieldsets
+# for several resource at a time (e.g. an included related resource in an field
+# of another resource) with <tt>fields[object_type]</tt> parameters.
 #
 #   GET /posts?fields[posts]=id,title,author&fields[user]=id,name,avatar_url
 #
 # Note: +author+ of a +post+ is a +user+.
 #
 # The +fields+ and <tt>fields[object_type]</tt> parameters can not be mixed.
-# If the latter format is used, then it must be used for the main object as well.
+# If the latter format is used, then it must be used for the main resource as
+# well.
 #
 # == Usage
 #
@@ -38,26 +41,35 @@ require 'active_support'
 # or in your Grape API class:
 #
 #   class SampleAPI < Grape::API
-#     include APIHelper::Fieldsettable
+#     helpers APIHelper::Fieldsettable
 #   end
 #
-# then set the options for the fieldset in the grape method:
+# Then set fieldset with +fieldset_for+ for each resource in the controller:
+#
+#   def index
+#     fieldset_for :post, default: true, default_fields: [:id, :title, :author]
+#     fieldset_for :user, permitted_fields: [:id, :name, :posts, :avatar_url],
+#                         defaults_to_permitted_fields: true
+#     # ...
+#   end
+#
+# or in the Grape method if you're using Grape:
 #
 #   resources :posts do
 #     get do
-#       fieldset_for :post, root: true, default_fields: [:id, :title, :author]
+#       fieldset_for :post, default: true, default_fields: [:id, :title, :author]
 #       fieldset_for :user, permitted_fields: [:id, :name, :posts, :avatar_url],
-#                           show_all_permitted_fields_by_default: true
+#                           defaults_to_permitted_fields: true
 #       # ...
 #     end
 #   end
 #
-# This helper parses the +fields+ and <tt>fields[object_type]</tt> parameters to
-# determine what the API caller wants, and save the results into instance
-# variables for further usage.
+# The +fieldset_for+ method used above parses the +fields+ and/or
+# <tt>fields[resource_name]</tt> parameters, and save the results into
+# +@fieldset+ instance variable for further usage.
 #
-# After this you can use the +fieldset+ helper method to get the fieldset data
-# that the request specifies.
+# After that line, you can use the +fieldset+ helper method to get the fieldset
+# information. Actual examples are:
 #
 # With <tt>GET /posts?fields=title,author</tt>:
 #
@@ -70,26 +82,53 @@ require 'active_support'
 #   fieldset(:post, :title) #=> true
 #   fieldset(:user, :avatar_url) #=> false
 #
-# You can make use of the information while dealing with requests, for example:
+# You can make use of these information while dealing with requests in the
+# controller, for example:
+#
+#   Post.select(fieldset(:post)).find(params[:id])
+#
+# And return only specified fields in the view, for instance, Jbuilder:
+#
+#   json.(@post, *fieldset(:post))
+#   json.author do
+#     json.(@author, *fieldset(:user))
+#   end
+#
+# or RABL:
+#
+#   # post.rabl
 #
-#   Post.select(fieldset(:post))...
+#   object @post
+#   attributes(*fieldset[:post])
+#   child :author do
+#     extends 'user'
+#   end
+#
+#   # user.rabl
+#
+#   object @user
+#   attributes(*fieldset[:user])
 #
-# If you're using RABL as the API view, it can be also setup like this:
+# You can also set properties of fieldset with the +set_fieldset+ helper method
+# in the views if you're using a same view across multiple controllers, for
+# decreasing code duplication or increasing security. Below is an example with
+# RABL:
 #
 #   object @user
 #
-#   # this ensures the +fieldset+ instance variable is least setted with
-#   # the default fields, and double check +permitted_fields+ at view layer -
-#   # in case of things going wrong in the controller
+#   # this ensures that the +fieldset+ instance variable is least setted with
+#   # the default fields, and double filters +permitted_fields+ at view layer -
+#   # in case of any things going wrong in the controller
 #   set_fieldset :user, default_fields: [:id, :name, :avatar_url],
 #                       permitted_fields: [:id, :name, :avatar_url, :posts]
 #
 #   # determine the fields to show on the fly
 #   attributes(*fieldset[:user])
+#
 module APIHelper::Fieldsettable
   extend ActiveSupport::Concern
 
-  # Gets the fields parameters, organize them into a +@fieldset+ hash for model to select certain
+  # Gets the fields parameters, organize them into a +@fieldset+ hash for model to select certain.
   # fields and/or templates to render specified fieldset. Following the URL rules of JSON API:
   # http://jsonapi.org/format/#fetching-sparse-fieldsets
   #
@@ -98,8 +137,9 @@ module APIHelper::Fieldsettable
   # +resource+::
   #   +Symbol+ name of resource to receive the fieldset
   #
-  # +root+::
-  #   +Boolean+ should this resource take the parameter from +fields+ while no type is specified
+  # +default+::
+  #   +Boolean+ should this resource take the parameter from +fields+ while no
+  #             resourse name is specified?
   #
   # +permitted_fields+::
   #   +Array+ of +Symbol+s list of accessible fields used to filter out unpermitted fields,
@@ -108,9 +148,9 @@ module APIHelper::Fieldsettable
   # +default_fields+::
   #   +Array+ of +Symbol+s list of fields to show by default
   #
-  # +show_all_permitted_fields_by_default+::
-  #   +Boolean+ if set to true, @fieldset will be set to all permitted_fields when the current
-  #   resource's fieldset isn't specified
+  # +defaults_to_permitted_fields+::
+  #   +Boolean+ if set to true, @fieldset will be set to all permitted_fields
+  #   when the current resource's fieldset isn't specified
   #
   # Example Result:
   #
@@ -121,46 +161,88 @@ module APIHelper::Fieldsettable
   #     #                :user => [:id, :name, :email, :groups],
   #     #                :group => [:id, :name]
   #     #              }
-  def fieldset_for(resource, root: false, permitted_fields: [], show_all_permitted_fields_by_default: false, default_fields: [])
-    @fieldset ||= Hashie::Mash.new
-    @meta ||= Hashie::Mash.new
+  #
+  def fieldset_for(resource, default: false,
+                             permitted_fields: [],
+                             defaults_to_permitted_fields: false,
+                             default_fields: [])
+    @fieldset ||= ActiveSupport::HashWithIndifferentAccess.new
 
     # put the fields in place
-    if params[:fields].is_a? Hash
+    if params[:fields].is_a?(Hash)
+      # get the specific resource fields from fields hash
       @fieldset[resource] = params[:fields][resource] || params[:fields][resource]
-    elsif root
+    elsif default
+      # or get the fields string directly if this resource is th default one
       @fieldset[resource] = params[:fields]
     end
 
-    # splits the string into array of symbles
-    @fieldset[resource] = @fieldset[resource].present? ? @fieldset[resource].split(',').map(&:to_sym) : default_fields
+    # splits the string into array
+    if @fieldset[resource].present?
+      @fieldset[resource] = @fieldset[resource].split(',').map(&:to_s)
+    else
+      @fieldset[resource] = default_fields.map(&:to_s)
+    end
 
-    # filter out unpermitted fields by intersecting them
-    @fieldset[resource] &= permitted_fields if @fieldset[resource].present? && permitted_fields.present?
+    if permitted_fields.present?
+      permitted_fields = permitted_fields.map(&:to_s)
 
-    # set default fields to permitted_fields if needed
-    @fieldset[resource] = permitted_fields if show_all_permitted_fields_by_default && @fieldset[resource].blank? && permitted_fields.present?
-  end
+      # filter out unpermitted fields by intersecting them
+      @fieldset[resource] &= permitted_fields if @fieldset[resource].present?
 
-  # View Helper to set the default and permitted fields
-  def set_fieldset(resource, default_fields: [], permitted_fields: [])
-    @fieldset ||= {}
-    @fieldset[resource] = default_fields if @fieldset[resource].blank?
-    @fieldset[resource] &= permitted_fields
+      # set default fields to permitted_fields if needed
+      @fieldset[resource] = permitted_fields if @fieldset[resource].blank? &&
+                                                defaults_to_permitted_fields
+    end
   end
 
   # Getter for the fieldset data
+  #
+  # This method will act as a traditional getter of the fieldset data and
+  # returns a hash containing fields for each resource if no parameter is
+  # provided.
+  #
+  #   fieldset  # => { 'user' => ['name'], 'post' => ['title', 'author'] }
+  #
+  # If one parameter - a specific resourse name is passed in, it will return
+  # a fields array of that specific resourse.
+  #
+  #   fieldset(:post)  # => ['title', 'author']
+  #
+  # And if one more parameter - a field name, is passed in, it will return a
+  # boolen, determining if that field should exist in that resource.
+  #
+  #   fieldset(:post, :title)  # => true
+  #
   def fieldset(resource = nil, field = nil)
+    # act as a traditional getter if no parameters specified
     if resource.blank?
-      @fieldset ||= {}
+      @fieldset ||= ActiveSupport::HashWithIndifferentAccess.new
+
+    # returns the fieldset array if an specific resource is passed in
     elsif field.blank?
-      (@fieldset ||= {})[resource] ||= []
+      fieldset[resource] || []
+
+    # determine if a field is inculded in a specific fieldset
     else
-      fieldset(resource).include?(field)
+      field = field.to_s
+      fieldset(resource).is_a?(Array) && fieldset(resource).include?(field)
     end
   end
 
-  # Return the 'fields' param description
+  # View Helper to set the default and permitted fields
+  #
+  # This is useful while using an resource view shared by multiple controllers,
+  # it will ensure the +@fieldset+ instance variable presents, and can also set
+  # the default fields of a model for convenience, or the whitelisted permitted
+  # fields for security.
+  def set_fieldset(resource, default_fields: [], permitted_fields: [])
+    @fieldset ||= ActiveSupport::HashWithIndifferentAccess.new
+    @fieldset[resource] = default_fields.map(&:to_s) if @fieldset[resource].blank?
+    @fieldset[resource] &= permitted_fields.map(&:to_s) if permitted_fields.present?
+  end
+
+  # Returns the description of the 'fields' URL parameter
   def self.fields_param_desc(example: nil)
     if example.present?
       "Choose the fields to be returned. Example value: '#{example}'"
@@ -168,4 +250,10 @@ module APIHelper::Fieldsettable
       "Choose the fields to be returned."
     end
   end
+
+  included do
+    if defined? helper_method
+      helper_method :fieldset, :set_fieldset
+    end
+  end
 end

data/lib/api_helper/filterable.rb

@@ -1,9 +1,10 @@
 require 'active_support'
+require 'active_support/core_ext/object/blank'
 
-# = Helper To Make Resource APIs Filterable
+# = Filterable
 #
-# A filterable resource API supports requests to filter resources according to
-# specific criteria, using the +filter+ query parameter.
+# A filterable resource API supports requests to filter resources in collection
+# by their fields, using the +filter+ query parameter.
 #
 # For example, the following is a request for all products that has a
 # particular color:
@@ -16,19 +17,23 @@ require 'active_support'
 #
 # <em>Multiple filters are applied with the AND condition.</em>
 #
-# OR conditions of a single value can be represented as:
+# A list separated by commas (",") can be used to filter by field matching one
+# of the values:
 #
 #   GET /products?filter[color]=red,blue,yellow
 #
 # A few functions: +not+, +greater_then+, +less_then+, +greater_then_or_equal+,
-# +less_then_or_equal+, +between+ and +like+ can be used while filtering
-# the data, for example:
+# +less_then_or_equal+, +between+, +like+, +contains+, +null+ and +blank+ can
+# be used to filter the data, for example:
 #
 #   GET /products?filter[color]=not(red)
 #   GET /products?filter[price]=greater_then(1000)
 #   GET /products?filter[price]=less_then_or_equal(2000)
 #   GET /products?filter[price]=between(1000,2000)
 #   GET /products?filter[name]=like(%lovely%)
+#   GET /products?filter[name]=contains(%lovely%)
+#   GET /products?filter[provider]=null()
+#   GET /products?filter[provider]=blank()
 #
 # == Usage
 #
@@ -41,20 +46,16 @@ require 'active_support'
 # or in your Grape API class:
 #
 #   class SampleAPI < Grape::API
-#     include APIHelper::Filterable
+#     helpers APIHelper::Filterable
 #   end
 #
-# then use the +filter+ method like this:
+# then use the +filter+ method in the controller like this:
 #
-#   resources :products do
-#     get do
-#       @products = filter(Post, filterable_fields: [:name, :price, :color])
-#       # ...
-#     end
-#   end
+#   @products = filter(Post, filterable_fields: [:name, :price, :color])
+#
+# <em>The +filter+ method will return a scoped model collection, based
+# directly from the requested URL parameters.</em>
 #
-# <em>The +filter+ method will return the scoped model, based directly
-# from the requested URL.</em>
 module APIHelper::Filterable
   extend ActiveSupport::Concern
 
@@ -63,20 +64,25 @@ module APIHelper::Filterable
   # Params:
   #
   # +resource+::
-  #   +ActiveRecord::Base+ or +ActiveRecord::Relation+ resource collection
+  #   +ActiveRecord::Relation+ resource collection
   #   to filter data from
   #
   # +filterable_fields+::
-  #   +Array+ of +Symbol+s fields that are allowed to be filtered, default
+  #   +Array+ of +Symbol+s fields that are allowed to be filtered, defaults
   #   to all
+  #
   def filter(resource, filterable_fields: [])
     # parse the request parameter
-    if params[:filter].is_a? Hash
+    if params[:filter].is_a?(Hash)
       @filter = params[:filter]
       filterable_fields = filterable_fields.map(&:to_s)
 
+      # deal with each condition
       @filter.each_pair do |field, condition|
+        # bypass fields that aren't be abled to filter with
         next if filterable_fields.present? && !filterable_fields.include?(field)
+
+        # escape string to prevent SQL injection
         field = resource.connection.quote_string(field)
 
         next if resource.columns_hash[field].blank?
@@ -89,22 +95,50 @@ module APIHelper::Filterable
             values = func[:param].split(',')
             values.map!(&:to_bool) if field_type == :boolean
             resource = resource.where.not(field => values)
+
           when 'greater_then'
-            resource = resource.where("\"#{resource.table_name}\".\"#{field}\" > ?", func[:param])
+            resource = resource
+                       .where("\"#{resource.table_name}\".\"#{field}\" > ?",
+                              func[:param])
+
           when 'less_then'
-            resource = resource.where("\"#{resource.table_name}\".\"#{field}\" < ?", func[:param])
+            resource = resource
+                       .where("\"#{resource.table_name}\".\"#{field}\" < ?",
+                              func[:param])
+
           when 'greater_then_or_equal'
-            resource = resource.where("\"#{resource.table_name}\".\"#{field}\" >= ?", func[:param])
+            resource = resource
+                       .where("\"#{resource.table_name}\".\"#{field}\" >= ?",
+                              func[:param])
+
           when 'less_then_or_equal'
-            resource = resource.where("\"#{resource.table_name}\".\"#{field}\" <= ?", func[:param])
+            resource = resource
+                       .where("\"#{resource.table_name}\".\"#{field}\" <= ?",
+                              func[:param])
+
           when 'between'
             param = func[:param].split(',')
-            resource = resource.where("\"#{resource.table_name}\".\"#{field}\" BETWEEN ? AND ?", param.first, param.last)
+            resource = resource
+                       .where("\"#{resource.table_name}\".\"#{field}\" BETWEEN ? AND ?",
+                              param.first, param.last)
+
           when 'like'
-            resource = resource.where("\"#{resource.table_name}\".\"#{field}\" LIKE ?", func[:param])
+            resource = resource
+                       .where("\"#{resource.table_name}\".\"#{field}\" LIKE ?",
+                              func[:param])
+
+          when 'contains'
+            resource = resource
+                       .where("\"#{resource.table_name}\".\"#{field}\" LIKE ?",
+                              "%#{func[:param]}%")
+
           when 'null'
             resource = resource.where(field => nil)
+
+          when 'blank'
+            resource = resource.where(field => [nil, ''])
           end
+
         # if not function
         else
           values = condition.split(',')
@@ -117,7 +151,7 @@ module APIHelper::Filterable
     return resource
   end
 
-  # Return the 'fields' param description
+  # Returns a description of the 'fields' URL parameter
   def self.filter_param_desc(for_field: nil)
     if for_field.present?
       "Filter data base on the '#{for_field}' field."
@@ -126,3 +160,9 @@ module APIHelper::Filterable
     end
   end
 end
+
+class String
+  def to_bool
+    self == 'true'
+  end
+end

data/lib/api_helper/includable.rb

@@ -1,16 +1,16 @@
 require 'active_support'
 
-# = Helper To Make Resource APIs Includable
+# = Includable
 #
-# Inclusion of related resource lets your API return resources related to the
-# primary data. This endpoint will support an +include+ request parameter to
-# allow the client to customize which related resources should be returned.
+# Inclusion lets your API returns not only the data of the primary resource,
+# but also resources that have relation to it. Includable APIs will also
+# support customising the resources included using the +include+ parameter.
 #
 # This design made references to the rules of <em>Inclusion of Related
 # Resources</em> in <em>JSON API</em>:
 # http://jsonapi.org/format/#fetching-includes
 #
-# For instance, comments could be requested with articles:
+# For instance, articles can be requested with their comments along:
 #
 #   GET /articles?include=comments
 #
@@ -57,7 +57,7 @@ require 'active_support'
 #     }
 #   ]
 #
-# instead of just:
+# instead of just the ids of each comment
 #
 #   [
 #     {
@@ -74,8 +74,8 @@ require 'active_support'
 #     }
 #   ]
 #
-# If requesting multiple related resources is needed, they can be stated in a
-# comma-separated list:
+# Multiple related resources can be stated in a comma-separated list,
+# like this:
 #
 #   GET /articles/12?include=author,comments
 #
@@ -90,118 +90,243 @@ require 'active_support'
 # or in your Grape API class:
 #
 #   class SampleAPI < Grape::API
-#     include APIHelper::Includable
+#     helpers APIHelper::Includable
+#   end
+#
+# Then setup inclusion with +inclusion_for+ in the controller:
+#
+#   def index
+#     inclusion_for :post, default: true
+#     # ...
 #   end
 #
-# then set the options for the inclusion in the grape method:
+# or in the Grape method if you're using it:
 #
 #   resources :posts do
 #     get do
-#       inclusion_for :post, root: true
+#       inclusion_for :post, default: true
 #       # ...
 #     end
 #   end
 #
-# This helper parses the +include+ and <tt>include[object_type]</tt> parameters to
-# determine what the API caller wants, and save the results into instance
-# variables for further usage.
+# This helper parses the +include+ and/or <tt>include[resource_name]</tt>
+# parameters and saves the results into +@inclusion+ for further usage.
+#
+# +Includable+ integrates with +Fieldsettable+ if used together, by:
+#
+# * Sliceing the included fields that dosen't appears in the fieldset - since
+#   the included resoure(s) are actually fields under the primary resorce,
+#   fieldset will be in charged to determine the fields to show. Thus, fields
+#   will be totally ignored if they aren't appeared in the fieldset, regardless
+#   if they are included or not.
+#
+# So notice that +inclusion_for+ should be set after +fieldset_for+ if both are
+# used!
 #
-# After this you can use the +inclusion+ helper method to get the inclusion data
-# that the request specifies, and do something like this in your controller:
+# After that +inclusion_for ...+ line, you can use the +inclusion+ helper
+# method to get the inclusion data of each request, and do something like this
+# in your controller:
 #
-#   resource = resource.includes(:author) if inclusion(:post, :author)
+#   @posts = Post.includes(inclusion(:post))
 #
-# The +inclusion+ helper method returns data like this:
+# The +inclusion+ helper method will return data depending on the parameters
+# passed in, as the following example:
 #
-#   inclusion #=> { post: [:author] }
-#   inclusion(:post) #=> [:author]
-#   inclusion(:post, :author) #=> true
+#   inclusion  # => { 'post' => ['author'] }
+#   inclusion(:post)  # => ['author']
+#   inclusion(:post, :author)  # => true
+#
+# And don't forget to set your API views or serializers with the help of
+# +inclusion+ to provide dynamic included resources!
 #
 # === API View with RABL
 #
 # If you're using RABL as the API view, it can be setup like this:
 #
+#   object @post
+#
 #   # set the includable and default inclusion fields of the view
 #   set_inclusion :post, default_includes: [:author]
 #
 #   # set the details for all includable fields
 #   set_inclusion_field :post, :author, :author_id
+#   set_inclusion_field :post, :comments, :comment_ids
 #
 #   # extends the partial to show included fields
 #   extends('extensions/includable_childs', locals: { self_resource: :post })
+#
+# --
+# TODO: provide an example of includable_childs.rabl
+# ++
+#
 module APIHelper::Includable
   extend ActiveSupport::Concern
 
-  # Gets the include parameters, organize them into a +@inclusion+ hash for model to use
-  # inner-join queries and/or templates to render relation attributes included.
-  # Following the URL rules of JSON API:
-  # http://jsonapi.org/format/#fetching-includes
+  # Gets the include parameters, organize them into a +@inclusion+ hash.
   #
   # Params:
   #
   # +resource+::
   #   +Symbol+ name of resource to receive the inclusion
-  def inclusion_for(resource, root: false, default_includes: [])
-    @inclusion ||= Hashie::Mash.new
-    @meta ||= Hashie::Mash.new
-
-    # put the includes in place
-    if params[:include].is_a? Hash
-      @inclusion[resource] = params[:include][resource] || params[:include][resource]
-    elsif root
+  #
+  # +default+::
+  #   +Boolean+ should this resource take the parameter from +include+ while no
+  #             resourse name is specified?
+  #
+  # +permitted_includes+::
+  #   +Array+ of +Symbol+s list of includable fields, permitting all by default
+  #
+  # +default_includes+::
+  #   +Array+ of +Symbol+s list of fields to be included by default
+  #
+  # +defaults_to_permitted_includes+::
+  #   +Boolean+ if set to true, +@inclusion+ will be set to all
+  #   permitted_includes when the current resource's included fields
+  #   isn't specified
+  #
+  def inclusion_for(resource, default: false,
+                              permitted_includes: [],
+                              defaults_to_permitted_includes: false,
+                              default_includes: [])
+    @inclusion ||= ActiveSupport::HashWithIndifferentAccess.new
+    @inclusion_specified ||= ActiveSupport::HashWithIndifferentAccess.new
+
+    # put the fields in place
+    if params[:include].is_a?(Hash)
+      # get the specific resource inclusion fields from the "include" hash
+      @inclusion[resource] = params[:include][resource]
+      @inclusion_specified[resource] = true if params[:include][resource].present?
+    elsif default
+      # or get the "include" string directly if this resource is th default one
       @inclusion[resource] = params[:include]
+      @inclusion_specified[resource] = true if params[:include].present?
     end
 
-    # splits the string into array of symbles
-    @inclusion[resource] = @inclusion[resource] ? @inclusion[resource].split(',').map(&:to_sym) : default_includes
-  end
+    # splits the string into array
+    if @inclusion[resource].present?
+      @inclusion[resource] = @inclusion[resource].split(',').map(&:to_s)
+    elsif !@inclusion_specified[resource]
+      @inclusion[resource] = default_includes.map(&:to_s)
+    end
 
-  # View Helper to set the inclusion and default_inclusion.
-  def set_inclusion(resource, default_includes: [])
-    @inclusion ||= {}
-    @inclusion_field ||= {}
-    @inclusion[resource] = default_includes if @inclusion[resource].blank?
-  end
+    if permitted_includes.present?
+      permitted_includes = permitted_includes.map(&:to_s)
 
-  # View Helper to set the inclusion details.
-  def set_inclusion_field(self_resource, field, id_field, class_name: nil, url: nil)
-    return if (@fieldset.present? && @fieldset[self_resource].present? && !@fieldset[self_resource].include?(field))
+      # filter out unpermitted includes by intersecting them
+      @inclusion[resource] &= permitted_includes if @inclusion[resource].present?
 
-    @inclusion_field ||= {}
-    @inclusion_field[self_resource] ||= []
-    field_data = {
-      field: field,
-      id_field: id_field,
-      class_name: class_name,
-      url: url
-    }
-    @inclusion_field[self_resource] << field_data
-    @fieldset[self_resource].delete(field) if @fieldset[self_resource].present?
+      # set default inclusion to permitted_includes if needed
+      @inclusion[resource] = permitted_includes if @inclusion[resource].blank? &&
+                                                   defaults_to_permitted_includes &&
+                                                   !@inclusion_specified[resource]
+    end
+
+    if @fieldset.is_a?(Hash) && @fieldset[resource].present?
+      @inclusion[resource] &= @fieldset[resource]
+    end
   end
 
   # Getter for the inclusion data.
+  #
+  # This method will act as a traditional getter of the inclusion data and
+  # returns a hash containing fields for each resource if no parameter is
+  # provided.
+  #
+  #   inclusion  # => { 'post' => ['author', 'comments'] }
+  #
+  # If one parameter - a specific resourse name is passed in, it will return an
+  # array of relation names that should be included for that specific resourse.
+  #
+  #   inclusion(:post)  # => ['author', 'comments']
+  #
+  # And if one more parameter - a field name, is passed in, it will return a
+  # boolen, determining if that relation should be included in the response.
+  #
+  #   inclusion(:post, :author)  # => true
+  #
   def inclusion(resource = nil, field = nil)
+    # act as a traditional getter if no parameters specified
     if resource.blank?
-      @inclusion ||= {}
+      @inclusion ||= ActiveSupport::HashWithIndifferentAccess.new
+
+    # returns the inclusion array if an specific resource is passed in
     elsif field.blank?
-      (@inclusion ||= {})[resource] ||= []
+      inclusion[resource] || []
+
+    # determine if a field is inculded
     else
-      return false if (try(:fieldset, resource).present? && !fieldset(resource, field))
-      inclusion(resource).include?(field)
+      field = field.to_s
+      inclusion(resource).is_a?(Array) && inclusion(resource).include?(field)
     end
   end
 
-  # Return the 'include' param description
+  # View Helper to set the inclusion
+  #
+  # This is useful while using an resource view shared by multiple controllers,
+  # this will ensure the +@inclusion+ instance variable presents, and can also
+  # set the default included fields of a model for convenience, or the fields
+  # that are permitted to be included for security.
+  def set_inclusion(resource, default_includes: [], permitted_includes: [])
+    @inclusion ||= ActiveSupport::HashWithIndifferentAccess.new
+    @inclusion_field ||= ActiveSupport::HashWithIndifferentAccess.new
+    @inclusion[resource] = default_includes.map(&:to_s) if @inclusion[resource].blank? &&
+                                                           !@inclusion_specified[resource]
+    @inclusion[resource] &= permitted_includes.map(&:to_s) if permitted_includes.present?
+  end
+
+  # View Helper to set the inclusion details
+  #
+  # Params:
+  #
+  # +resource+::
+  #   +Symbol+ name of the resource to receive the inclusion field data
+  #
+  # +field+::
+  #   +Symbol+ the field name of the relatiion that can be included
+  #
+  # +id_field+::
+  #   +Symbol+ the field to use (normally suffixed with "_id") if the object
+  #   isn't included
+  #
+  # +resource_name+::
+  #   +Symbol+ the name of the child resource, can be used to determine which
+  #   view template should be extended for rendering that child node and also
+  #   can shown in the response metadata as well
+  #
+  # +resources_url+::
+  #   +String+ the resources URL of the child resource, can be used to be shown
+  #   in the metadata for the clients' convenience to learn ablou the API
+  #
+  def set_inclusion_field(resource, field, id_field, resource_name: nil,
+                                                     resources_url: nil)
+    @inclusion_field ||= ActiveSupport::HashWithIndifferentAccess.new
+    @inclusion_field[resource] ||= ActiveSupport::HashWithIndifferentAccess.new
+    @inclusion_field[resource][field] = {
+      field: field,
+      id_field: id_field,
+      resource_name: resource_name,
+      resources_url: resources_url
+    }
+  end
+
+  # Returns the description of the 'include' URL parameter
   def self.include_param_desc(example: nil, default: nil)
     if default.present?
       desc = "Returning compound documents that include specific associated objects, defaults to '#{default}'."
     else
       desc = "Returning compound documents that include specific associated objects."
     end
+
     if example.present?
       "#{desc} Example value: '#{example}'"
     else
       desc
     end
   end
+
+  included do
+    if defined? helper_method
+      helper_method :inclusion, :set_inclusion, :set_inclusion_field
+    end
+  end
 end

data/lib/api_helper/version.rb

@@ -1,3 +1,3 @@
 module APIHelper
-  VERSION = "0.0.2"
+  VERSION = "0.0.3"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: api_helper
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
 platform: ruby
 authors:
 - Neson
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2015-06-12 00:00:00.000000000 Z
+date: 2015-06-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -38,6 +38,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: appraisal
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -52,6 +66,48 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: byebug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: activesupport
   requirement: !ruby/object:Gem::Requirement
@@ -76,12 +132,20 @@ files:
 - ".gitignore"
 - ".rspec"
 - ".travis.yml"
+- Appraisals
 - Gemfile
 - README.md
 - Rakefile
 - api_helper.gemspec
 - bin/console
 - bin/setup
+- examples/includable_childs.rabl
+- gemfiles/grape_0.10.0.gemfile
+- gemfiles/grape_0.11.0.gemfile
+- gemfiles/rails_4.0.0.gemfile
+- gemfiles/rails_4.1.0.gemfile
+- gemfiles/rails_4.1.8.gemfile
+- gemfiles/rails_4.2.0.gemfile
 - lib/api_helper.rb
 - lib/api_helper/fieldsettable.rb
 - lib/api_helper/filterable.rb
@@ -114,3 +178,4 @@ signing_key:
 specification_version: 4
 summary: Helpers for creating standard web API.
 test_files: []
+has_rdoc: