apique 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: c185ec939c0e1327ab39f7a28e5c0d35c3638eb6
+  data.tar.gz: 446dbe26222728a725f071ff1682a40090f0178a
+SHA512:
+  metadata.gz: f522d9cedae7c11e5b1dbe3cf275435bb32141398c9648963352da0cb94daafff6d97918a3dbc99d9c4819f1e000d3dfc24948a332ce24d23944f6316f69ee20
+  data.tar.gz: 0194de1b634a6045f269945e9851c106ecde80358632bcb3f038bfb680547c02cf3ca7ec8b81098e727335429d52ead576350d9bf2bec511b3a4e9c81f439f84

data/.gitignore

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

data/Gemfile

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

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2016 Sergey Baev, https://github.com/tinbka
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,74 @@
+# Apique
+
+Apique modules replace tons of API cotrollers code which makes trivial actions including searching and CRUD, and provides front-end with thought-out errors and explanations.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'apique'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install apique
+
+## Usage
+
+There is 8 modules with the following hierarchy:
+```
+- Basics (auth)
+- - Pickable (singular actions)
+- - - Editable (singular write actions)
+- - Listable (plural actions)
+- - - Filterable
+- - - Sortable
+- - - Paginatable
+- - - Searchable (sum of the previous 3)
+```
+Modules suppose to be injected into an ActionController instance to provide needed functional, for example
+```ruby
+# In Rails 5 you may also want to inherit from ActionController::API
+class ApiController < ApplicationController
+  include Apique::Searchable
+  include Apique::Editable
+end
+```
+Since ApiController has both highest-level modules injected, it now provides all the functional and default controller actions which utilize all the power of Apique.
+
+Now what is left is to make routes to these actions. In future releases it will be done by one engine mount based on the definition of #collection_name method.
+
+```ruby
+  get 'api/:model' => 'api#index'
+  get 'api/:model/:id' => 'api#show'
+  post 'api/:model' => 'api#create'
+  patch 'api/:model/:id' => 'api#update'
+  delete 'api/:model/:id' => 'api#destroy'
+```
+
+In order to create controllers with _specific_ actions, just inherit from ApiController (in this example) and define routes... as usual!
+
+## Current restrictions
+
+For the moment #filter_collection! used in #index works only with PostgreSQL and #sort_collection! used in #index works only with SQL databases.
+There will be support for other SQL DBs and Mongoid in the future.
+
+## TODO
+
+Describe search facilities and future plans.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. 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/tinbka/apique.
+

data/Rakefile

@@ -0,0 +1,2 @@
+require "bundler/gem_tasks"
+task :default => :spec

data/apique.gemspec

@@ -0,0 +1,26 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'apique/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "apique"
+  spec.version       = Apique::VERSION
+  spec.authors       = ["Sergey Baev"]
+  spec.email         = ["tinbka@gmail.com"]
+
+  spec.summary       = %q{Rails CRUD API replacement}
+  spec.description   = %q{Apique modules replace tons of API cotrollers code which makes trivial actions including searching and CRUD, and provides front-end with thought-out errors and explanations.}
+  spec.homepage      = "https://github.com/tinbka/apique"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  #spec.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.11"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec", "~> 3.3"
+  
+  spec.add_dependency "cancancan"
+  spec.add_dependency "rails"
+end

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "apique"
+
+# 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,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/apique.rb

@@ -0,0 +1,14 @@
+require "apique/version"
+
+module Apique
+  extend ActiveSupport::Autoload
+  
+  autoload :Basics
+  autoload :Editable
+  autoload :Filterable
+  autoload :Listable
+  autoload :Paginatable
+  autoload :Pickable
+  autoload :Searchable
+  autoload :Sortable
+end

data/lib/apique/basics.rb

@@ -0,0 +1,51 @@
+# Basic functional for API implementation.
+module Apique::Basics
+  extend ActiveSupport::Concern
+  
+  included do
+    protect_from_forgery with: :null_session
+  
+    before_action :authorize_access
+    
+    rescue_from CanCan::AccessDenied do |e|
+      render json: {error: e.message}, status: :forbidden
+    end
+    
+    rescue_from NotImplementedError do |e|
+      render json: {error: e.message}, status: :not_acceptable
+    end
+  end
+  
+  
+  private
+  
+  ### Authorization ###
+  
+  # @virtual
+  # Used to immediately halt request processing before any other action would be done.
+  # E.g. call `authorize! :access, :admin` inside an admin-only controller
+  # or check a token in a secure public controller.
+  def authorize_access
+  end
+  
+  
+  ### Basic getters-setters ###
+  
+  # @return [Ability]
+  def current_ability
+    @current_ability ||= Ability.new current_user
+  end
+  
+  # The plural name of the ORM class.
+  # @return [String]
+  def collection_name
+    @collection_name ||= params[:model]
+  end
+
+  # The ORM class of the resource.
+  # @return [Class]
+  def resource_class
+    @resource_class ||= collection_name.singularize.classify.constantize
+  end
+  
+end

data/lib/apique/editable.rb

@@ -0,0 +1,67 @@
+# Basic functional for creating, updating, and destroying records.
+module Apique::Editable
+  extend ActiveSupport::Concern
+  include Apique::Pickable
+  
+  included do
+    rescue_from ActionController::ParameterMissing do |e|
+      render json: {error: e.message}, status: :bad_request
+    end
+    
+    rescue_from ActionController::UnpermittedParameters, ActiveModel::ForbiddenAttributesError do |e|
+      render json: {error: e.message}, status: :unprocessable_entity
+    end  
+  end
+  
+  
+  # A resource is already built by CanCan according to load_resource params in the current controller.
+  # POST /api/{plural_resource_name}
+  def create
+    if get_resource.save
+      render :show, status: :created
+    else
+      render json: {errors: get_resource.errors}
+    end
+  end
+
+  # PATCH/PUT /api/{plural_resource_name}/{id}
+  def update
+    if get_resource.update(update_api_params)
+      render :show
+    else
+      render json: {errors: get_resource.errors}
+    end
+  end
+
+  # DELETE /api/{plural_resource_name}/{id}
+  def destroy
+    get_resource.destroy
+    unless get_resource.errors.present?
+      on_destroy
+    else
+      render json: {errors: get_resource.errors}
+    end
+  end
+  
+  
+  private
+  
+  ### Default callbacks ###
+  
+  def on_destroy
+    head :no_content
+  end
+  
+  
+  ### Basic getters-setters ###
+  
+  # Only allow a trusted parameter "white list" through.
+  # If a single resource is loaded for #create or #update,
+  # then the controller for the resource must implement
+  # the method "update_params" to limit permitted
+  # parameters for the individual model.
+  def update_api_params
+    @resource_params ||= self.send('update_params')
+  end
+  
+end

data/lib/apique/filterable.rb

@@ -0,0 +1,91 @@
+# Basic functional to perform detailed filtering inside record collections.
+module Apique::Filterable
+  extend ActiveSupport::Concern
+  include Apique::Listable
+  
+  included do
+    params_usage['q'] = {
+      desc: "q [String] filter by a value of a default field (optional)",
+      example: "q=abc requests to filter a default column(s) by abc substring"
+    }
+    params_usage['q[]'] = {
+      desc: "q [Object] filter by a value of a field specified as object key (optional, overrides plain `q')",
+      example: "q[amount]=123&q[title_or_description]=abc requests to filter by amount equal to 123 AND (title OR description contains abc substring)"
+    }
+    params_types['q'] = [String, Hash]
+  end
+  
+  
+  private
+  
+  ### Basic getters-setters ###
+  
+  # @abstract
+  # Filter by this column implicitly when q=value is passed. Supports field_or_field2 notation.
+  # @return [String]
+  def default_filter_column
+    raise NotImplementedError, "A developer must implement default_filter_column for this controller to allow plain `q' query parameter."
+  end
+  
+  
+  ### Whitelists ###
+  
+  # @virtual
+  # Pattern method for params a user can filter by. Add whitelisting logic in a descendant using `super`.
+  # @return [ActionController::Parameters]
+  def filter_params
+    params[:q].presence || ActionController::Parameters.new
+  end
+  
+  
+  ### Collection filters ###
+  
+  # Filter the current collection with {column_or_scope => value, ... } Hash within params[:q]
+  # @return [DB collection proxy]
+  def filter_collection!
+    if params[:q].is_a? String
+      params[:q] = {default_filter_column => params[:q]}
+      return filter_collection!
+    end
+    
+    if filter_params.present?
+      collection = get_collection
+        
+      filter_params.each do |k, v|
+        next if v.blank?
+          
+        if resource_class.respond_to? "search_by_#{k}"
+          # A call to a scope. A method must be defined as a scope to work on another ORM relation.
+          collection = collection.public_send "search_by_#{k}", v
+        else
+          is_text = [ActiveRecord::Type::String, ActiveRecord::Type::Text].include? resource_class.columns.find {|i| i.name == k}.cast_type
+          
+          if k =~ /_or_/
+            fields = k.split('_or_')
+            
+            if is_text
+              collection = collection.where [
+                fields.map {|i| "#{i} ILIKE ?"} * ' OR ',
+                *(["%#{v}%"] * fields.size)
+              ]
+            else
+              collection = collection.where [
+                fields.map {|i| "#{i} = ?"} * ' OR ',
+                *([v] * fields.size)
+              ]
+            end
+          else
+            if is_text
+              collection = collection.where ["#{k} ILIKE ?", "%#{v}%"]
+            else
+              collection = collection.where k => v
+            end
+          end
+        end
+      end
+      
+      set_collection collection
+    end
+  end
+  
+end

data/lib/apique/listable.rb

@@ -0,0 +1,103 @@
+# Basic functional for retrieving collections of records.
+module Apique::Listable
+  extend ActiveSupport::Concern
+  include Apique::Basics
+  
+  included do
+    # [Hash: param_key_string => {:desc, :example}]
+    class_attribute :params_usage
+    self.params_usage = {}
+    # [Hash: param_key_string => param_types_array]
+    class_attribute :params_types
+    self.params_types = {}
+    
+    helper_method :subject_collection
+  
+    before_action :validate_query, only: :index
+    
+    rescue_from Apique::MalformedParameters do |e|
+      render json: e, status: :bad_request
+    end
+  end
+  
+  
+  # Exception will raise if a request query would contain an incorrect of malformed parameter.
+  # This will provide the front-end with a description of the correct API usage.
+  class Apique::MalformedParameters < Exception
+    
+    def initialize(request, param, params_usage, *args)
+      message = "Bad request query: malformed parameter #{param}"
+      usage = "GET #{request.fullpath[/[^?]+/]}?#{params_usage.keys*'&'}"
+      
+      @json = {message: message, usage: usage, params: params_usage.values}
+      
+      message = [
+        message, "Usage: #{usage}",
+        *params_usage.values.flat_map {|v| [v[:desc], "Example: #{v[:example]}"]}
+      ]*"\n"
+      
+      super(message, *args)
+    end
+    
+    def as_json(*)
+      @json
+    end
+    
+  end
+  
+  
+  # GET /api/{plural_resource_name}
+  def index
+    if respond_to? :filter_collection!, true
+      filter_collection!
+    end
+    if respond_to? :sort_collection!, true
+      sort_collection!
+    end
+    if respond_to? :paginate_collection!, true
+      paginate_collection!
+    end
+    render json: subject_collection
+  end
+  
+  
+  private
+  
+  ### Basic getters-setters ###
+
+  # Returns the collection from the created instance variable.
+  # @return [DB collection proxy]
+  def get_collection
+    instance_variable_get("@#{collection_name}") || set_collection
+  end
+  
+  # Used as a helper to create DRYed json builders in inheritable controllers.
+  alias_method :subject_collection, :get_collection
+
+  # Puts the collection into an instance variable.
+  # In most cases, the collection exactly allowed for the user by CanCan rules should be an entry point.
+  # @return [DB collection proxy]
+  def set_collection(collection = resource_class.accessible_by(current_ability))
+    instance_variable_set("@#{collection_name}", collection)
+  end
+  
+  
+  ### Whitelists ###
+  
+  # Check consistency of a query parameters for a list. Use it as a before filter if needed.
+  # @raise [MalformedParameters] if the request query is malformed.
+  def validate_query
+    request.query_parameters.each do |k, v|
+      param_is_valid = self.class.params_types.find do |name, types|
+        if k == name
+          break true if types.any? {|type| v.is_a? type}
+          raise MalformedParameters.new(request, k, self.class.params_usage)
+        end
+      end
+      unless param_is_valid
+        raise MalformedParameters.new(request, k, self.class.params_usage)
+      end
+    end
+  end
+  
+end

data/lib/apique/paginatable.rb

@@ -0,0 +1,38 @@
+# Basic functional for paginating record collections.
+module Apique::Paginatable
+  extend ActiveSupport::Concern
+  include Apique::Listable
+  
+  included do
+    class_attribute :per_page
+    
+    params_usage['page'] = {
+      desc: "",
+      example: "page=20"
+    }
+    params_types['page'] = [String]
+    
+    set_per_page 25
+  end
+  
+  module ClassMethods
+    
+    def set_per_page(number)
+      self.per_page = number
+      params_usage['page'][:desc] = "page [Integer] 1-based number of a bunch of #{number} items list (optional)"
+    end
+    
+  end
+  
+  
+  private
+  
+  ### Collection filters ###
+  
+  # Get 1-based params[:page]-th page of the current collection.
+  # @return [DB collection proxy]
+  def paginate_collection!
+    set_collection get_collection.page(params[:page]).per(self.class.per_page)
+  end
+  
+end

data/lib/apique/pickable.rb

@@ -0,0 +1,56 @@
+# Basic functional for retrieving discrete records.
+module Apique::Pickable
+  extend ActiveSupport::Concern
+  include Apique::Basics
+  
+  included do
+    helper_method :subject_resource
+  
+    rescue_from ActiveRecord::RecordNotFound, Apique::RecordNotFound do |e|
+      render json: {error: e.message}, status: :not_found
+    end
+  end
+  
+  # This exception will be raised if a request would query for an inexisted record and
+  # this case would not have been handled by CanCan.
+  class Apique::RecordNotFound < ActionController::RoutingError; end
+  
+  
+  # GET /api/{plural_resource_name}/{id}
+  def show
+    render json: subject_resource
+  end
+  
+  
+  private
+  
+  ### Basic getters-setters ###
+
+  # The singular name of the ORM class.
+  # @return [String]
+  def resource_name
+    @resource_name ||= collection_name.singularize
+  end
+
+  # Returns the resource from the created instance variable.
+  # @return [Object]
+  def get_resource
+    instance_variable_get("@#{resource_name}") || set_resource
+  end
+  
+  # Used as a helper to create DRYed json builders in inheritable controllers.
+  alias_method :subject_resource, :get_resource
+
+  # Puts the resource into an instance variable.
+  # @raise [ActionController::RoutingError] if there is no resource found.
+  # @return [Object]
+  def set_resource(resource = nil)
+    resource ||= resource_class.find(params[:id])
+    unless resource
+      raise RecordNotFound, "could not find a record of type #{resource_class} with id = #{params[:id]}"
+    end
+    
+    instance_variable_set("@#{resource_name}", resource)
+  end
+  
+end

data/lib/apique/searchable.rb

@@ -0,0 +1,7 @@
+# Just a shortcut for inclusion.
+module Apique::Searchable
+  extend ActiveSupport::Concern
+  include Apique::Filterable
+  include Apique::Sortable
+  include Apique::Paginatable
+end

data/lib/apique/sortable.rb

@@ -0,0 +1,50 @@
+# Basic functional for ordering record collections.
+module Apique::Sortable
+  extend ActiveSupport::Concern
+  include Apique::Listable
+  
+  included do
+    params_usage['s'] = {
+      desc: "s [Object] sort by a field in a specified direction (optional)",
+      example: "s[id]=1&s[name]=-1&s[price] requests to sort by by id (most recent last), name (Z to A), and price (lower to higher)"
+    }
+    params_types['s'] = [Hash]
+  end
+  
+  
+  private
+  
+  ### Whitelists ###
+  
+  # @virtual
+  # Pattern method for params a user can sort by. Add whitelisting logic in a descendant using `super`.
+  # @return [ActionController::Parameters]
+  def sort_params
+    params[:s].presence || ActionController::Parameters.new
+  end
+  
+  
+  ### Collection filters ###
+  
+  # Sort the current collection by {column => direction, ... } Hash within params[:s]
+  # @return [DB collection proxy]
+  def sort_collection!
+    collection = get_collection
+    
+    if sort_params.present?
+      sort_params.each do |k, v|
+        if v.present? and ['desc', '-1'].include? v.downcase
+          collection = collection.order "#{k} desc"
+        else
+          collection = collection.order "#{k} asc"
+        end
+      end
+    end
+    if collection.order_values.blank?
+      collection = collection.order "id desc"
+    end
+    
+    set_collection collection
+  end
+  
+end

data/lib/apique/version.rb

@@ -0,0 +1,3 @@
+module Apique
+  VERSION = "1.0.0"
+end

metadata

@@ -0,0 +1,133 @@
+--- !ruby/object:Gem::Specification
+name: apique
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Sergey Baev
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2016-04-23 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.11'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.11'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.3'
+- !ruby/object:Gem::Dependency
+  name: cancancan
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Apique modules replace tons of API cotrollers code which makes trivial
+  actions including searching and CRUD, and provides front-end with thought-out errors
+  and explanations.
+email:
+- tinbka@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- apique.gemspec
+- bin/console
+- bin/setup
+- lib/apique.rb
+- lib/apique/basics.rb
+- lib/apique/editable.rb
+- lib/apique/filterable.rb
+- lib/apique/listable.rb
+- lib/apique/paginatable.rb
+- lib/apique/pickable.rb
+- lib/apique/searchable.rb
+- lib/apique/sortable.rb
+- lib/apique/version.rb
+homepage: https://github.com/tinbka/apique
+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.8
+signing_key: 
+specification_version: 4
+summary: Rails CRUD API replacement
+test_files: []