api_helper 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 991d12decd2615a223eebef7da4c5f132c47dfe6
+  data.tar.gz: 9bafcbeafb95c36abf2f5b091cec2b995b47a43e
+SHA512:
+  metadata.gz: 78f5748409ee50cb19af1c70f9e73a35fb82dd72caff6d3b3009394ed7208c092525805bd6b41cd476693dd48243ccaca9bd4f6c003889cbf6614318dae16799
+  data.tar.gz: 11e33204b137a30a922d8c57d603d517c176f3bdce2f6cb3420fea31de524fb151c1348c55a2df32d330016eab88879b6e3eb3a4f2e7e776048b7de00bfd3603

data/.gitignore

@@ -0,0 +1,9 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/.travis.yml

@@ -0,0 +1,4 @@
+language: ruby
+rvm:
+  - 2.2.0
+before_install: gem install bundler -v 1.10.2

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in api_helper.gemspec
+gemspec

data/README.md

@@ -0,0 +1,94 @@
+# APIHelper
+
+Helpers for creating standard RESTful API for Rails or Grape with Active Record.
+
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'APIHelper'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install APIHelper
+
+
+## API Standards
+
+<dl>
+
+  <dt><a href="http://www.rubydoc.info/github/Neson/api_helper/master/APIHelper/Fieldsettable" target="_blank">Fieldsettable</a></dt>
+  <dd>Let clients choose the fields they wanted to be returned with the "fields" query parameter, making their API calls optimizable to gain efficiency and speed.</dd>
+
+  <dt><a href="http://www.rubydoc.info/github/Neson/api_helper/master/APIHelper/Includable" target="_blank">Includable</a></dt>
+  <dd>Clients can use the "include" query parameter to enable inclusion of related items - for instance, get the author's data along with a post.</dd>
+
+  <dt><a href="http://www.rubydoc.info/github/Neson/api_helper/master/APIHelper/Paginatable" target="_blank">Paginatable</a></dt>
+  <dd>Paginate the results of a resource collection, client can get a specific page with the "page" query parameter and set a custom page size with the "per_page" query parameter.</dd>
+
+  <dt><a href="http://www.rubydoc.info/github/Neson/api_helper/master/APIHelper/Sortable" target="_blank">Sortable</a></dt>
+  <dd>Client can set custom sorting with the "sort" query parameter while getting a resource collection.</dd>
+
+  <dt><a href="http://www.rubydoc.info/github/Neson/api_helper/master/APIHelper/Filterable" target="_blank">Filterable</a></dt>
+  <dd>Enables clients to filter through a resource collection with their fields.</dd>
+
+  <dt><a href="http://www.rubydoc.info/github/Neson/api_helper/master/APIHelper/Multigettable" target="_blank">Multigettable</a></dt>
+  <dd>Let Client execute operations on multiple resources with a single request.</dd>
+
+</dl>
+
+
+## Usage
+
+### Ruby on Rails (Action Pack)
+
+Include each helper concern you need in an `ActionController::Base`:
+
+```ruby
+PostsController < ApplicationController
+  include APIHelpers::Filterable
+  include APIHelpers::Paginatable
+  include APIHelpers::Sortable
+
+  # ...
+
+end
+```
+
+Further usage of each helper can be found in the docs.
+
+### Grape
+
+Set the helpers you need in an `Grape::API`:
+
+```ruby
+class PostsAPI < Grape::API
+  helpers APIHelpers::Filterable
+  helpers APIHelpers::Paginatable
+  helpers APIHelpers::Sortable
+
+  # ...
+
+end
+```
+
+Further usage of each helper can be found in the docs.
+
+
+## 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.
+
+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.

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/api_helper.gemspec

@@ -0,0 +1,26 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'api_helper/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "api_helper"
+  spec.version       = APIHelper::VERSION
+  spec.authors       = ["Neson"]
+  spec.email         = ["neson@dex.tw"]
+
+  spec.summary       = %q{Helpers for creating standard web API.}
+  spec.description   = %q{Helpers for creating standard web API for Rails or Grape with ActiveRecord.}
+  spec.homepage      = "https://github.com/Neson/APIHelper"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "rspec"
+
+  spec.add_development_dependency "activesupport", ">= 3"
+end

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "api_helper"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start

data/bin/setup

@@ -0,0 +1,7 @@
+#!/bin/bash
+set -euo pipefail
+IFS=$'\n\t'
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/api_helper/fieldsettable.rb

@@ -0,0 +1,171 @@
+require 'active_support'
+
+# = Helper To Make Resource APIs 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.
+#
+# 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.
+#
+#   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.
+#
+#   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.
+#
+# == Usage
+#
+# Include this +Concern+ in your Action Controller:
+#
+#   SamplesController < ApplicationController
+#     include APIHelper::Fieldsettable
+#   end
+#
+# or in your Grape API class:
+#
+#   class SampleAPI < Grape::API
+#     include APIHelper::Fieldsettable
+#   end
+#
+# then set the options for the fieldset in the grape method:
+#
+#   resources :posts do
+#     get do
+#       fieldset_for :post, root: true, default_fields: [:id, :title, :author]
+#       fieldset_for :user, permitted_fields: [:id, :name, :posts, :avatar_url],
+#                           show_all_permitted_fields_by_default: 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.
+#
+# After this you can use the +fieldset+ helper method to get the fieldset data
+# that the request specifies.
+#
+# With <tt>GET /posts?fields=title,author</tt>:
+#
+#   fieldset #=> { post: [:title, :author], user: [:id, :name, :posts, :avatar_url] }
+#
+# With <tt>GET /posts?fields[post]=title,author&fields[user]=name</tt>:
+#
+#   fieldset #=> { post: [:title, :author], user: [:name] }
+#   fieldset(:post) #=> [:title, :author]
+#   fieldset(:post, :title) #=> true
+#   fieldset(:user, :avatar_url) #=> false
+#
+# You can make use of the information while dealing with requests, for example:
+#
+#   Post.select(fieldset(:post))...
+#
+# If you're using RABL as the API view, it can be also setup like this:
+#
+#   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
+#   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
+  # fields and/or templates to render specified fieldset. Following the URL rules of JSON API:
+  # http://jsonapi.org/format/#fetching-sparse-fieldsets
+  #
+  # Params:
+  #
+  # +resource+::
+  #   +Symbol+ name of resource to receive the fieldset
+  #
+  # +root+::
+  #   +Boolean+ should this resource take the parameter from +fields+ while no type is specified
+  #
+  # +permitted_fields+::
+  #   +Array+ of +Symbol+s list of accessible fields used to filter out unpermitted fields,
+  #   defaults to permit all
+  #
+  # +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
+  #
+  # Example Result:
+  #
+  #     fieldset_for :user, root: true
+  #     fieldset_for :group
+  #
+  #     # @fieldset => {
+  #     #                :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
+
+    # put the fields in place
+    if params[:fields].is_a? Hash
+      @fieldset[resource] = params[:fields][resource] || params[:fields][resource]
+    elsif root
+      @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
+
+    # filter out unpermitted fields by intersecting them
+    @fieldset[resource] &= permitted_fields if @fieldset[resource].present? && permitted_fields.present?
+
+    # 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
+
+  # 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
+  end
+
+  # Getter for the fieldset data
+  def fieldset(resource = nil, field = nil)
+    if resource.blank?
+      @fieldset ||= {}
+    elsif field.blank?
+      (@fieldset ||= {})[resource] ||= []
+    else
+      fieldset(resource).include?(field)
+    end
+  end
+
+  # Return the 'fields' param description
+  def self.fields_param_desc(example: nil)
+    if example.present?
+      "Choose the fields to be returned. Example value: '#{example}'"
+    else
+      "Choose the fields to be returned."
+    end
+  end
+end

data/lib/api_helper/filterable.rb

@@ -0,0 +1,128 @@
+require 'active_support'
+
+# = Helper To Make Resource APIs Filterable
+#
+# A filterable resource API supports requests to filter resources according to
+# specific criteria, using the +filter+ query parameter.
+#
+# For example, the following is a request for all products that has a
+# particular color:
+#
+#   GET /products?filter[color]=red
+#
+# With this approach, multiple filters can be applied to a single request:
+#
+#   GET /products?filter[color]=red&filter[status]=in-stock
+#
+# <em>Multiple filters are applied with the AND condition.</em>
+#
+# OR conditions of a single value can be represented as:
+#
+#   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:
+#
+#   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%)
+#
+# == Usage
+#
+# Include this +Concern+ in your Action Controller:
+#
+#   SamplesController < ApplicationController
+#     include APIHelpers::Filterable
+#   end
+#
+# or in your Grape API class:
+#
+#   class SampleAPI < Grape::API
+#     include APIHelper::Filterable
+#   end
+#
+# then use the +filter+ method like this:
+#
+#   resources :products do
+#     get do
+#       @products = filter(Post, filterable_fields: [:name, :price, :color])
+#       # ...
+#     end
+#   end
+#
+# <em>The +filter+ method will return the scoped model, based directly
+# from the requested URL.</em>
+module APIHelper::Filterable
+  extend ActiveSupport::Concern
+
+  # Filter resources of a collection from the request parameter
+  #
+  # Params:
+  #
+  # +resource+::
+  #   +ActiveRecord::Base+ or +ActiveRecord::Relation+ resource collection
+  #   to filter data from
+  #
+  # +filterable_fields+::
+  #   +Array+ of +Symbol+s fields that are allowed to be filtered, default
+  #   to all
+  def filter(resource, filterable_fields: [])
+    # parse the request parameter
+    if params[:filter].is_a? Hash
+      @filter = params[:filter]
+      filterable_fields = filterable_fields.map(&:to_s)
+
+      @filter.each_pair do |field, condition|
+        next if filterable_fields.present? && !filterable_fields.include?(field)
+        field = resource.connection.quote_string(field)
+
+        next if resource.columns_hash[field].blank?
+        field_type = resource.columns_hash[field].type
+
+        # if a function is used
+        if func = condition.match(/(?<function>[^\(\)]+)\((?<param>.*)\)/)
+          case func[:function]
+          when 'not'
+            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])
+          when 'less_then'
+            resource = resource.where("\"#{resource.table_name}\".\"#{field}\" < ?", func[:param])
+          when 'greater_then_or_equal'
+            resource = resource.where("\"#{resource.table_name}\".\"#{field}\" >= ?", func[:param])
+          when 'less_then_or_equal'
+            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)
+          when 'like'
+            resource = resource.where("\"#{resource.table_name}\".\"#{field}\" LIKE ?", func[:param])
+          when 'null'
+            resource = resource.where(field => nil)
+          end
+        # if not function
+        else
+          values = condition.split(',')
+          values.map!(&:to_bool) if field_type == :boolean
+          resource = resource.where(field => values)
+        end
+      end
+    end
+
+    return resource
+  end
+
+  # Return the 'fields' param description
+  def self.filter_param_desc(for_field: nil)
+    if for_field.present?
+      "Filter data base on the '#{for_field}' field."
+    else
+      "Filter the data."
+    end
+  end
+end

data/lib/api_helper/includable.rb

@@ -0,0 +1,207 @@
+require 'active_support'
+
+# = Helper To Make Resource APIs 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.
+#
+# 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:
+#
+#   GET /articles?include=comments
+#
+# The server will respond
+#
+#   [
+#     {
+#       "id": 1,
+#       "title": "First Post",
+#       "content": "...",
+#       "comments": [
+#         {
+#           "id": 1,
+#           "content": "..."
+#         },
+#         {
+#           "id": 3,
+#           "content": "..."
+#         },
+#         {
+#           "id": 6,
+#           "content": "..."
+#         }
+#       ]
+#     },
+#     {
+#       "id": 2,
+#       "title": "Second Post",
+#       "content": "...",
+#       "comments": [
+#         {
+#           "id": 2,
+#           "content": "..."
+#         },
+#         {
+#           "id": 4,
+#           "content": "..."
+#         },
+#         {
+#           "id": 5,
+#           "content": "..."
+#         }
+#       ]
+#     }
+#   ]
+#
+# instead of just:
+#
+#   [
+#     {
+#       "id": 1,
+#       "title": "First Post",
+#       "content": "...",
+#       "comments": [1, 3, 6]
+#     },
+#     {
+#       "id": 2,
+#       "title": "Second Post",
+#       "content": "...",
+#       "comments": [2, 4, 5]
+#     }
+#   ]
+#
+# If requesting multiple related resources is needed, they can be stated in a
+# comma-separated list:
+#
+#   GET /articles/12?include=author,comments
+#
+# == Usage
+#
+# Include this +Concern+ in your Action Controller:
+#
+#   SamplesController < ApplicationController
+#     include APIHelper::Includable
+#   end
+#
+# or in your Grape API class:
+#
+#   class SampleAPI < Grape::API
+#     include APIHelper::Includable
+#   end
+#
+# then set the options for the inclusion in the grape method:
+#
+#   resources :posts do
+#     get do
+#       inclusion_for :post, root: 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.
+#
+# 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:
+#
+#   resource = resource.includes(:author) if inclusion(:post, :author)
+#
+# The +inclusion+ helper method returns data like this:
+#
+#   inclusion #=> { post: [:author] }
+#   inclusion(:post) #=> [:author]
+#   inclusion(:post, :author) #=> true
+#
+# === API View with RABL
+#
+# If you're using RABL as the API view, it can be setup like this:
+#
+#   # 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
+#
+#   # extends the partial to show included fields
+#   extends('extensions/includable_childs', locals: { self_resource: :post })
+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
+  #
+  # 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
+      @inclusion[resource] = params[:include]
+    end
+
+    # splits the string into array of symbles
+    @inclusion[resource] = @inclusion[resource] ? @inclusion[resource].split(',').map(&:to_sym) : default_includes
+  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
+
+  # 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))
+
+    @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?
+  end
+
+  # Getter for the inclusion data.
+  def inclusion(resource = nil, field = nil)
+    if resource.blank?
+      @inclusion ||= {}
+    elsif field.blank?
+      (@inclusion ||= {})[resource] ||= []
+    else
+      return false if (try(:fieldset, resource).present? && !fieldset(resource, field))
+      inclusion(resource).include?(field)
+    end
+  end
+
+  # Return the 'include' param description
+  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
+end

data/lib/api_helper/multigettable.rb

@@ -0,0 +1,82 @@
+require 'active_support'
+
+# = Helper To Make Resource APIs Multigettable
+#
+# A normal resource API can let clients retrieve one specified data at a time:
+#
+#   GET /posts/3
+#
+# If it's declared to be multigettable, then clients can retrieve multiple
+# specified data like this:
+#
+#   GET /posts/3,4,8,9
+#
+# == Usage
+#
+# Include this +Concern+ in your Action Controller:
+#
+#   SamplesController < ApplicationController
+#     include APIHelper::Multigettable
+#   end
+#
+# or in your Grape API class:
+#
+#   class SampleAPI < Grape::API
+#     include 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
+#
+# <em>The +multiget+ method returns a array 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
+#
+# 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 ','
+  #
+  # Params:
+  #
+  # +resource+::
+  #   +ActiveRecord::Base+ or +ActiveRecord::Relation+ resource collection
+  #   to find data from
+  #
+  # +find_by+::
+  #   +Symbol+ the attribute that is used to find data
+  #
+  # +max+::
+  #   +Integer+ maxium count of returning results
+  def multiget(resource, find_by: :id, max: 10)
+    ids = params[find_by].split(',')
+    ids = ids[0..(max - 1)]
+
+    if ids.count > 1
+      resource.where(find_by => ids)
+    else
+      resource.find_by(find_by => ids[0])
+    end
+  end
+
+  # Is the a multiget request?
+  def multiget?(find_by: :id)
+    params[find_by].include?(',')
+  end
+end

data/lib/api_helper/paginatable.rb

@@ -0,0 +1,140 @@
+require 'active_support'
+
+# = Helper To Make Resource APIs 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.
+#
+# 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
+# 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>
+#
+# Use the +page+ parameter to specify which to retrieve:
+#
+#   GET /posts?page=5
+#
+# Pagination info will be provided in the HTTP Link header like this:
+#
+#   Link: <http://api-server.dev/movies?page=1>; rel="first",
+#         <http://api-server.dev/movies?page=4>; rel="prev"
+#         <http://api-server.dev/movies?page=6>; rel="next",
+#         <http://api-server.dev/movies?page=238>; rel="last"
+#
+# <em>Line breaks are added for readability.</em>
+#
+# Which follows the proposed RFC 5988 standard.
+#
+# == Usage
+#
+# Include this +Concern+ in your Action Controller:
+#
+#   SamplesController < ApplicationController
+#     include APIHelper::Paginatable
+#   end
+#
+# or in your Grape API class:
+#
+#   class SampleAPI < Grape::API
+#     include APIHelper::Paginatable
+#   end
+#
+# then set the options for pagination in the grape method:
+#
+#   resources :posts do
+#     get do
+#       pagination User.count, default_per_page: 25, maxium_per_page: 100
+#
+#       # ...
+#     end
+#   end
+#
+# Then use the helper methods, like this:
+#
+#   User.page(page).per(per_page)
+#
+# HTTP Link header will be automatically set.
+module APIHelper::Paginatable
+  extend ActiveSupport::Concern
+
+  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
+
+    items_count = 0 if items_count < 0
+    pages_count = (items_count.to_f / @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
+
+    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
+
+    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)
+      end
+
+      if defined?(response) && response.respond_to?(:headers)
+        response.headers['Link'] = link_header
+        response.headers['X-Items-Count'] = items_count.to_s
+      end
+    end
+
+    link_header
+  end
+
+  # Getter for the current page
+  def page
+    @page
+  end
+
+  alias_method :current_page, :page
+
+  # Getter for per_page
+  def per_page
+    @per_page
+  end
+
+  alias_method :page_with, :per_page
+
+  def add_or_replace_uri_param(url, param_name, param_value)
+    uri = URI(url)
+    params = URI.decode_www_form(uri.query || '')
+    params.delete_if { |param| param[0].to_s == param_name.to_s }
+    params << [param_name, param_value]
+    uri.query = URI.encode_www_form(params)
+    uri.to_s
+  end
+
+  # Return the 'per_page' param description
+  def self.per_page_param_desc
+    "Specify how many items you want each page to return."
+  end
+
+  # Return the 'page' param description
+  def self.page_param_desc
+    "Specify which page you want to get."
+  end
+end

data/lib/api_helper/sortable.rb

@@ -0,0 +1,89 @@
+require 'active_support'
+
+# = Helper To Make Resource APIs Sortable
+#
+# A Sortable Resource API gives the flexibility to change how the returned data
+# is sorted to the client. Clients can use the +sort+ URL parameter to control
+# how the returned data is sorted, as this example:
+#
+#   GET /posts?sort=-created_at,title
+#
+# This means to sort the data by its created time descended and then the title
+# ascended.
+#
+# == Usage
+#
+# Include this +Concern+ in your Action Controller:
+#
+#   SamplesController < ApplicationController
+#     include APIHelper::Sortable
+#   end
+#
+# or in your Grape API class:
+#
+#   class SampleAPI < Grape::API
+#     include APIHelper::Sortable
+#   end
+#
+# then use the +sortable+ method like this:
+#
+#   resources :posts do
+#     get do
+#       sortable default_order: { created_at: :desc }
+#       # ...
+#       @posts = Post.order(sort)#...
+#       # ...
+#     end
+#   end
+module APIHelper::Sortable
+  extend ActiveSupport::Concern
+
+  # Gets the `sort` parameter with the format 'resourses?sort=-created_at,name',
+  # verify and converts it into an safe Hash that can be passed into the .order
+  # method.
+  #
+  # Params:
+  #
+  # +default_order+::
+  #   +Hash+ the default value to return if the sort parameter is not provided
+  def sortable(default_order: {})
+    # get the parameter
+    sort_by = params[:sort] || params[:sort_by]
+
+    if sort_by.is_a? String
+      # split it
+      sort_by_attrs = sort_by.gsub(/[^a-zA-Z0-9\-_,]/, '').split(',')
+
+      # save it
+      @sort = {}
+      sort_by_attrs.each do |attrb|
+        if attrb.match(/^-/)
+          @sort[attrb.gsub(/^-/, '')] = :desc
+        else
+          @sort[attrb] = :asc
+        end
+      end
+    else
+      @sort = default_order
+    end
+  end
+
+  # Helper to get the sort data
+  def sort
+    @sort
+  end
+
+  # Return the 'sort' param description
+  def self.sort_param_desc(example: nil, default: nil)
+    if default.present?
+      desc = "Specify how the returning data should be sorted, defaults to '#{default}'."
+    else
+      desc = "Specify how the returning data should be sorted."
+    end
+    if example.present?
+      "#{desc} Example value: '#{example}'"
+    else
+      desc
+    end
+  end
+end

data/lib/api_helper/version.rb

@@ -0,0 +1,3 @@
+module APIHelper
+  VERSION = "0.0.1"
+end

data/lib/api_helper.rb

@@ -0,0 +1,10 @@
+require "api_helper/version"
+require "api_helper/fieldsettable"
+require "api_helper/includable"
+require "api_helper/paginatable"
+require "api_helper/sortable"
+require "api_helper/filterable"
+require "api_helper/multigettable"
+
+module APIHelper
+end

metadata

@@ -0,0 +1,116 @@
+--- !ruby/object:Gem::Specification
+name: api_helper
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Neson
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2015-06-12 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  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: rake
+  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
+    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
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3'
+description: Helpers for creating standard web API for Rails or Grape with ActiveRecord.
+email:
+- neson@dex.tw
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".travis.yml"
+- Gemfile
+- README.md
+- Rakefile
+- api_helper.gemspec
+- bin/console
+- bin/setup
+- lib/api_helper.rb
+- lib/api_helper/fieldsettable.rb
+- lib/api_helper/filterable.rb
+- lib/api_helper/includable.rb
+- lib/api_helper/multigettable.rb
+- lib/api_helper/paginatable.rb
+- lib/api_helper/sortable.rb
+- lib/api_helper/version.rb
+homepage: https://github.com/Neson/APIHelper
+licenses: []
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.6
+signing_key: 
+specification_version: 4
+summary: Helpers for creating standard web API.
+test_files: []