api_helper 0.0.3 → 0.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 326e1e9e2c1b9509990e1103a0d8f95da5be83a9
-  data.tar.gz: 4c9fd145828a49a586d8a4b7dee67fa177ea957c
+  metadata.gz: 1adf4979040c0208985d4361607511531fb29f52
+  data.tar.gz: ceca06658f81cb44773d226dbda4f6961c7c864d
 SHA512:
-  metadata.gz: d14e69fb29488afe354b941fc4501ba92620936731673a2bc41274cf37f77bd4f2fbcf7e368e9dd8cc52e473a4b9b8ce1fd1b49391d59f6e638df0fac6452eda
-  data.tar.gz: f44a72e00cc934ad01194d0c20fa799f0fc6e232d26abced40f6a60b120b6942b66db0d3e21bfa90496ecc10e0b51b84833ad77727ebb2b85363dd1a5c7e5177
+  metadata.gz: 5dcc39614587391601e8537c9589377d00aea011b10d77dbd0b0aedc42235cef97fe85904a6d2a772a87f7775239a92b4168007c2ba25e4ded5aad56abcc473c
+  data.tar.gz: 69634679a2a32c1338e6bcd616f73e907cc33d02235adfc0ab34ea61f9c3979a9a01a4e013f030a9768ef88502194bbd42e54aeb99e0e3ad401af671cb4d1497

data/lib/api_helper/includable.rb

@@ -162,7 +162,7 @@ require 'active_support'
 module APIHelper::Includable
   extend ActiveSupport::Concern
 
-  # Gets the include parameters, organize them into a +@inclusion+ hash.
+  # Gets the include parameters, organize them into a +@inclusion+ hash
   #
   # Params:
   #
@@ -226,7 +226,7 @@ module APIHelper::Includable
     end
   end
 
-  # Getter for the inclusion data.
+  # 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

data/lib/api_helper/multigettable.rb

@@ -1,16 +1,22 @@
 require 'active_support'
 
-# = Helper To Make Resource APIs Multigettable
+# = Multigettable
 #
-# A normal resource API can let clients retrieve one specified data at a time:
+# A normal RESTful API can let clients get one specified resource at a time:
 #
 #   GET /posts/3
 #
-# If it's declared to be multigettable, then clients can retrieve multiple
-# specified data like this:
+# If it's declared to be multigettable, then clients can get multiple
+# specified resource like this:
 #
 #   GET /posts/3,4,8,9
 #
+# An API may also support applying operations on multiple resource sith a
+# single request using this approach
+#
+#   PATCH /posts/3,4,8,9
+#   DELETE /posts/3,4,8,9
+#
 # == Usage
 #
 # Include this +Concern+ in your Action Controller:
@@ -22,50 +28,43 @@ require 'active_support'
 # or in your Grape API class:
 #
 #   class SampleAPI < Grape::API
-#     include APIHelper::Multigettable
+#     helpers APIHelper::Multigettable
 #   end
 #
 # then use the +multiget+ method like this:
 #
-#   resources :posts do
-#     # ...
-#     get :id do
-#       @post = multiget(Post, find_by: :id, max: 12)
-#       # ...
-#     end
-#   end
+#   @post = multiget(Post, find_by: :id, param: :id, max: 12)
 #
-# <em>The +multiget+ method returns a array of or a single model, based
+# <em>The +multiget+ method returns an collection of or a single model, based
 # directly from the requested URL.</em>
 #
 # There is also another helper method to determine whether the request is
 # multigeting or not:
 #
-#   multiget?(find_by: id) #=> true of false
+#   multiget?(param: id)  # => true of false
 #
-# It can be used to interact with other condition and functionalities,
-# like this:
-#
-#   inclusion_for :post, root: true,
-#     default_includes: (multiget?(find_by: :id) ? [] : [:author])
 module APIHelper::Multigettable
   extend ActiveSupport::Concern
 
-  # Get multiple resources from a resource URL by specifing ids split by ','
+  # Get multiple resources from the request by specifing ids split by ','
   #
   # Params:
   #
   # +resource+::
-  #   +ActiveRecord::Base+ or +ActiveRecord::Relation+ resource collection
-  #   to find data from
+  #   +ActiveRecord::Relation+ resource collection to find resources from
   #
   # +find_by+::
-  #   +Symbol+ the attribute that is used to find data
+  #   +Symbol+ the attribute that is used to find resources, defaults to :id
+  #
+  # +param+::
+  #   +Symbol+ the request parameter name used to find resources,
+  #   defaults to :id
   #
   # +max+::
   #   +Integer+ maxium count of returning results
-  def multiget(resource, find_by: :id, max: 10)
-    ids = params[find_by].split(',')
+  #
+  def multiget(resource, find_by: :id, param: :id, max: 10)
+    ids = params[param].split(',')
     ids = ids[0..(max - 1)]
 
     if ids.count > 1
@@ -76,7 +75,7 @@ module APIHelper::Multigettable
   end
 
   # Is the a multiget request?
-  def multiget?(find_by: :id)
-    params[find_by].include?(',')
+  def multiget?(param: :id)
+    params[param].present? && params[param].include?(',')
   end
 end

data/lib/api_helper/paginatable.rb

@@ -1,21 +1,21 @@
 require 'active_support'
 
-# = Helper To Make Resource APIs Paginatable
+# = Paginatable
 #
-# Paginating the requested items can avoid returning too much information
-# in a single response. API callers can iterate over the results using
-# pagination instead of rerteving all the data in one time, ruining the
-# database connection or network.
+# Paginating the requested items can avoid returning too much data in a single
+# response. API clients can iterate over the results with pagination instead of
+# rerteving all the data in one time, ruining the database connection or
+# network.
 #
-# There are two parameters clients can use: +per_page+ and +page+. The former
-# is used for setting how many data will be returned in each page, there will
+# There are two available URL parameters: +per_page+ and +page+. The former is
+# used for setting how many resources will be returned in each page, there will
 # be a maxium limit and default value for each API:
 #
 #   GET /posts?per_page=10
 #
-# <em>The server will respond 10 items at a time.</em>
+# <em>The server will respond 10 resources in a request.</em>
 #
-# Use the +page+ parameter to specify which to retrieve:
+# Use the +page+ parameter to specify which to page get:
 #
 #   GET /posts?page=5
 #
@@ -30,6 +30,9 @@ require 'active_support'
 #
 # Which follows the proposed RFC 5988 standard.
 #
+# An aditional header, +X-Items-Count+, will also be set to the total pages
+# count.
+#
 # == Usage
 #
 # Include this +Concern+ in your Action Controller:
@@ -41,85 +44,104 @@ require 'active_support'
 # or in your Grape API class:
 #
 #   class SampleAPI < Grape::API
-#     include APIHelper::Paginatable
+#     helpers APIHelper::Paginatable
 #   end
 #
-# then set the options for pagination in the grape method:
+# then set the options for pagination in the grape method, as the following as
+# an example:
 #
 #   resources :posts do
 #     get do
-#       pagination User.count, default_per_page: 25, maxium_per_page: 100
+#       collection = current_user.posts
+#       pagination collection.count, default_per_page: 25, maxium_per_page: 100
 #
 #       # ...
 #     end
 #   end
 #
-# Then use the helper methods, like this:
+# Then use the helper methods like this:
 #
+#   # this example uses kaminari
 #   User.page(page).per(per_page)
 #
-# HTTP Link header will be automatically set.
+# HTTP Link header will be automatically set by the way.
 module APIHelper::Paginatable
   extend ActiveSupport::Concern
 
-  def pagination(items_count, default_per_page: 20, maxium_per_page: 100, set_header: true)
+  # Set pagination for the request
+  #
+  # Params:
+  #
+  # +items_count+::
+  #   +Symbol+ name of resource to receive the inclusion
+  #
+  # +default_per_page+::
+  #   +Integer+ default per_page
+  #
+  # +maxium_per_page+::
+  #   +Integer+ maximum results do return on a single page
+  #
+  def pagination(items_count, default_per_page: 20,
+                              maxium_per_page: 100,
+                              set_header: true)
     items_count = items_count.count if items_count.respond_to? :count
 
-    @per_page = (params[:per_page] || default_per_page).to_i
-    @per_page = maxium_per_page if @per_page > maxium_per_page
-    @per_page = 1 if @per_page < 1
+    @pagination_per_page = (params[:per_page] || default_per_page).to_i
+    @pagination_per_page = maxium_per_page if @pagination_per_page > maxium_per_page
+    @pagination_per_page = 1 if @pagination_per_page < 1
 
     items_count = 0 if items_count < 0
-    pages_count = (items_count.to_f / @per_page).ceil
+    pages_count = (items_count.to_f / @pagination_per_page).ceil
     pages_count = 1 if pages_count < 1
 
-    @page = (params[:page] || 1).to_i
-    @page = pages_count if @page > pages_count
-    @page = 1 if @page < 1
+    @pagination_page = (params[:page] || 1).to_i
+    @pagination_page = pages_count if @pagination_page > pages_count
+    @pagination_page = 1 if @pagination_page < 1
 
-    link_headers ||= []
+    if set_header
+      link_headers ||= []
 
-    if current_page < pages_count
-      link_headers << "<#{add_or_replace_uri_param(request.url, :page, current_page + 1)}>; rel=\"next\""
-      link_headers << "<#{add_or_replace_uri_param(request.url, :page, pages_count)}>; rel=\"last\""
-    end
-    if current_page > 1
-      link_headers << "<#{add_or_replace_uri_param(request.url, :page, (current_page > pages_count ? pages_count : current_page - 1))}>; rel=\"prev\""
-      link_headers << "<#{add_or_replace_uri_param(request.url, :page, 1)}>; rel=\"first\""
-    end
+      if current_page > 1
+        link_headers << "<#{add_or_replace_uri_param(request.url, :page, 1)}>; rel=\"first\""
+        link_headers << "<#{add_or_replace_uri_param(request.url, :page, (current_page > pages_count ? pages_count : current_page - 1))}>; rel=\"prev\""
+      end
 
-    link_header = link_headers.join(', ')
+      if current_page < pages_count
+        link_headers << "<#{add_or_replace_uri_param(request.url, :page, current_page + 1)}>; rel=\"next\""
+        link_headers << "<#{add_or_replace_uri_param(request.url, :page, pages_count)}>; rel=\"last\""
+      end
+
+      link_header = link_headers.join(', ')
 
-    if set_header
       if self.respond_to?(:header)
         self.header('Link', link_header)
         self.header('X-Items-Count', items_count.to_s)
+        self.header('X-Pages-Count', pages_count.to_s)
       end
 
       if defined?(response) && response.respond_to?(:headers)
         response.headers['Link'] = link_header
         response.headers['X-Items-Count'] = items_count.to_s
+        response.headers['X-Pages-Count'] = pages_count.to_s
       end
     end
-
-    link_header
   end
 
   # Getter for the current page
-  def page
-    @page
+  def pagination_page
+    @pagination_page
   end
 
-  alias_method :current_page, :page
+  alias_method :current_page, :pagination_page
 
   # Getter for per_page
-  def per_page
-    @per_page
+  def pagination_per_page
+    @pagination_per_page
   end
 
-  alias_method :page_with, :per_page
+  alias_method :paginate_with, :pagination_per_page
 
-  def add_or_replace_uri_param(url, param_name, param_value)
+  def add_or_replace_uri_param(url, param_name, param_value) # :nodoc:
     uri = URI(url)
     params = URI.decode_www_form(uri.query || '')
     params.delete_if { |param| param[0].to_s == param_name.to_s }

data/lib/api_helper/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: api_helper
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.0.5
 platform: ruby
 authors:
 - Neson