Module: APIHelper::Filterable
- Extended by:
- ActiveSupport::Concern
- Defined in:
- lib/api_helper/filterable.rb
Overview
Filterable
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:
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
Multiple filters are applied with the AND condition.
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
, 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
Include this Concern
in your Action Controller:
SamplesController < ApplicationController
include APIHelper::Filterable
end
or in your Grape API class:
class SampleAPI < Grape::API
helpers APIHelper::Filterable
end
then use the filter
method in the controller like this:
@products = filter(Post, filterable_fields: [:name, :price, :color])
The filter
method will return a scoped model collection, based directly from the requested URL parameters.
Class Method Summary collapse
-
.filter_param_desc(for_field: nil) ⇒ Object
Returns a description of the ‘fields’ URL parameter.
Instance Method Summary collapse
-
#filter(resource, filterable_fields: [], ignore_unknown_fields: true) ⇒ Object
Filter resources of a collection from the request parameter.
Class Method Details
.filter_param_desc(for_field: nil) ⇒ Object
Returns a description of the ‘fields’ URL parameter
164 165 166 167 168 169 170 |
# File 'lib/api_helper/filterable.rb', line 164 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 |
Instance Method Details
#filter(resource, filterable_fields: [], ignore_unknown_fields: true) ⇒ Object
Filter resources of a collection from the request parameter
Params:
resource
-
ActiveRecord::Relation
resource collection to filter data from filterable_fields
-
Array
of Symbols fields that are allowed to be filtered, defaults to all
74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 |
# File 'lib/api_helper/filterable.rb', line 74 def filter(resource, filterable_fields: [], ignore_unknown_fields: true) # parse the request parameter if params[:filter].is_a?(Hash) || defined?(Rails) && Rails.version.to_i >= 5 && params[:filter].is_a?(ActionController::Parameters) @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 ignore_unknown_fields && resource.columns_hash[field].blank? field_type = resource.columns_hash[field] && resource.columns_hash[field].type || :unknown # if a function is used if func = condition.match(/(?<function>[^\(\)]+)\((?<param>.*)\)/) db_column_name = begin raise if ActiveRecord::Base.configurations[Rails.env]['adapter'] != 'mysql2' "`#{resource.table_name}`.`#{field}`" rescue "\"#{resource.table_name}\".\"#{field}\"" end 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("#{db_column_name} > ?", func[:param]) when 'less_then' resource = resource .where("#{db_column_name} < ?", func[:param]) when 'greater_then_or_equal' resource = resource .where("#{db_column_name} >= ?", func[:param]) when 'less_then_or_equal' resource = resource .where("#{db_column_name} <= ?", func[:param]) when 'between' param = func[:param].split(',') resource = resource .where("#{db_column_name} BETWEEN ? AND ?", param.first, param.last) when 'like' resource = resource .where("#{db_column_name} LIKE ?", func[:param]) when 'contains' resource = resource .where("#{db_column_name} 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(',') values.map!(&:to_bool) if field_type == :boolean resource = resource.where(field => values) end end end return resource end |