introspective_grape 0.1.9 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b9618a1c95e98590a625b563d4abd19954fd07fb
-  data.tar.gz: c8482ddba2d3dcacc302aee77420520c62823921
+  metadata.gz: d2f679318dbf2d22e2af0c95708eee64adf103fb
+  data.tar.gz: 786a80ed73eec2168392904e459266dda8b22663
 SHA512:
-  metadata.gz: 2522acc99b5c1a713ba0a254b00f586cac962c5ab777a6d11ac36b551700b9f3c8b7802f9dfbc23b20eddedfc05eafd53f4d6435a7a6fdbd58e266daa7f1582a
-  data.tar.gz: be83fbdf2ac3d282ab542915f8b1202223e4895b75d166cbf1ee46c3ff4a848e86b109ab2e26e8897e75b9e674b8b6c4cbf875f2d97cc962789f24bb948881f5
+  metadata.gz: 8ebf9eb5fd7859107a9d412cfe09728eb839191167b46cbd6d85ff9b1d740764cddc3acb621488c66e6b2d1a659f29c0b012c92948a35a478509e53012a5a5de
+  data.tar.gz: 9c8b93a2952bb15a2b8ba751efb1d49d00156a4267988068f91ce81ab71dad6860281b4d21c9d3424e6b162fd75fed26e835dbdf3e4d696d973e08700773ea1e

data/CHANGELOG.md

@@ -1,4 +1,31 @@
 
+0.2.0 10/12/2016
+==============
+
+### Features
+
+Allow index action filter overrides if there is a class-level 'assignment' method on the field
+
+Allow custom filters, e.g.:
+
+class MyAPI < IntrospectiveGrape::API
+  custom_filter :my_filter, {type: Boolean, description: "Filter on some scope" }
+
+  restful MyModel, [my_field]
+end
+
+class MyModel
+  self << class
+    def my_filter(filter=false)
+      filter ? my_scope : where(nil)
+    end
+    
+    def my_field=(parameters)
+      # parse the passed parameters in some fancy way and return a query scope
+    end
+  end 
+end
+
 0.1.9 9/27/2016
 ==============
 ### Features

data/README.md

@@ -77,7 +77,7 @@ In app/api/v1/my_model_api.rb:
 
 ```
 class MyModelAPI < IntrospectiveGrape::API
-  skip_presence_validations :attribute
+  skip_presence_validations :attribute_with_generated_default_value
   exclude_actions Model, <:index,:show,:create,:update,:destroy>
   default_includes Model, <associations for eager loading>
 
@@ -86,7 +86,7 @@ class MyModelAPI < IntrospectiveGrape::API
 
   paginate per_page 25, offset: 0, max_per_page: false
 
-  restful MyModel, [:strong, :param, :fields, :and, { nested_attributes: [:nested,:fields, :_destroy] }] do
+  restful MyModel, [:strong, :param, :fields, :and, { nested_model_attributes: [:nested,:fields, :_destroy] }] do
     # Add additional end points to the model's namespace
   end
  
@@ -111,7 +111,9 @@ types for the attributes specified in a hash, e.g.:
  
 ```
    def self.attribute_param_types
-    { "<attribute name>" => Virtus::Attribute::Boolean }
+    { "<attribute name 1>" => String,
+      "<attribute name 2>" => Integer,
+      "<attribute name 3>" => Virtus::Attribute::Boolean }
    end
 ```
 
@@ -120,9 +122,57 @@ nested params as well as nested routes will be declared, allowing for
 a good deal of flexibility for API consumers out of the box, such as implicitly
 creating bulk update endpoints for nested models.
 
+
+## Filtering and Searching
+
+IntrospectiveGrape will automatically generate and parse filters on all exposed fields in the API.
+
+Multiple values can be specified at once for Integer attributes that end in "id" (i.e. conventional primary and foreign keys) at once by passing a comma separated list of IDs.
+
+For timestamp attributes it will generate `<name_of_timestamp>_start` and `<name_of_timestamp>_end` constraints.
+
+### Overriding Filter Queries
+
+If, e.g., a field is some sort of complex composite rather than a simple field value you can override the default behavior (`where(field: params[field])`) by adding a query method on the model class:
+
+```
+class MyAPI < IntrospectiveGrape::API
+  restful MyModel, [my_composite_field]
+end
+
+class MyModel
+  self << class
+    def my_composite_field=(parameters)
+      # parse the passed parameters in some way and return a query scope
+    end
+  end
+end
+```
+
+### Custom Filter Methods
+
+To add a custom filter to the index action you can declare a method to be called
+against the model class with `custom_filter`. You can pass documentation and type
+constraints (it would default to String) and other Grape parameter options in a hash:
+
+```
+class MyAPI < IntrospectiveGrape::API
+  custom_filter :my_filter, type: Boolean, description: "Filter on some scope"
+end
+
+class MyModel
+  self << class
+    def my_filter(filter=false)
+      filter ? my_scope : where(nil)
+    end
+  end
+end
+```
+
+
 ## Pagination
 
-The index action by default will not be paginated, simply declared `paginate` before the `restful` declaration will enable [Kaminari](https://github.com/amatsuda/kaminari) pagination on the index results using a default 25 results per page with an offset of 0.
+The index action by default will not be paginated, simply declared `paginate` before the `restful` declaration will enable [Kaminari](https://github.com/amatsuda/kaminari) pagination on the index results using a default 25 results per page with an offset of 0. You can pass Kaminari's options to the paginate declaration, `per_page`, `max_per_page`, etc.
 
 ## Excluding Endpoints
 
@@ -136,7 +186,7 @@ declarations on the model. You can also include or exclude :all or :none as shor
 Grape only applies hooks in the order they were declared, so to hook into the default
 RESTful actions defined by IntrospectiveGrape you need to declare any hooks before the
 `restful` declaration, rather than inside its block, where the hook will only apply to
-subsequently declared endpoints.
+your own subsequently declared endpoints.
 
 
 ## Dependencies
@@ -146,11 +196,13 @@ Tool                  | Description
 [Grape]               | An opinionated micro-framework for creating REST-like APIs in Ruby
 [GrapeEntity]         | Adds Entity support to API frameworks, such as Grape.
 [GrapeSwagger]        | Swagger docs.
+[GrapeKaminari]       | Pagination.
 [Pundit]              | Minimal authorization through OO design and pure Ruby classes
 
-[Grape]:        https://github.com/ruby-grape/grape
-[GrapeEntity]:  https://github.com/ruby-grape/grape-entity
-[GrapeSwagger]: https://github.com/ruby-grape/grape-swagger
-[Pundit]:       https://github.com/elabs/pundit
+[Grape]:         https://github.com/ruby-grape/grape
+[GrapeEntity]:   https://github.com/ruby-grape/grape-entity
+[GrapeSwagger]:  https://github.com/ruby-grape/grape-swagger
+[GrapeKaminari]: https://github.com/monterail/grape-kaminari
+[Pundit]:        https://github.com/elabs/pundit
 
 

data/lib/introspective_grape/api.rb

@@ -28,7 +28,9 @@ module IntrospectiveGrape
     # types for the attributes specified in a hash:
     #
     #  def self.attribute_param_types
-    #   { "<attribute name>" => Virtus::Attribute::Boolean }
+    #   { "<attribute name>" => Virtus::Attribute::Boolean,
+    #     "<attribute name>" => Integer,
+    #     "<attribute name>" => String }
     #  end
     #
     # For nested models declared in Rails' strong params both the Grape params for the
@@ -88,6 +90,7 @@ module IntrospectiveGrape
         routes = build_routes(routes, model)
         define_routes(routes, whitelist)
 
+        # Top level declaration of the Grape::API namespace for the resource:
         resource routes.first.name.pluralize do
           # yield to append additional routes under the root namespace
           yield if block_given? 

data/lib/introspective_grape/filters.rb

@@ -1,7 +1,19 @@
 module IntrospectiveGrape::Filters
   #
-  # Allow filters on all whitelisted model attributes (from api_params)
+  # Allow filters on all whitelisted model attributes (from api_params) and declare
+  # customer filters for the index in a method.
   #
+
+  def custom_filter(*args)
+    custom_filters( *args )
+  end
+
+  def custom_filters(*args)
+    @custom_filters ||= {}
+    @custom_filters   = Hash[*args].merge(@custom_filters) if args.present?
+    @custom_filters
+  end
+
   def simple_filters(klass, model, api_params)
     @simple_filters ||= api_params.select {|p| p.is_a? Symbol }.map { |field|
       (klass.param_type(model,field) == DateTime ? ["#{field}_start", "#{field}_end"] : field.to_s)
@@ -33,11 +45,16 @@ module IntrospectiveGrape::Filters
         terminal = field.ends_with?("_start") ? "initial" : "terminal" 
         dsl.optional field, type: klass.param_type(model,field), description: "Constrain #{field} by #{terminal} date."
       elsif identifier_filter(klass,model,field)
-        dsl.optional field, type: Array[Integer], coerce_with: ->(val) { val.split(',') }
+        dsl.optional field, type: Array[Integer], coerce_with: ->(val) { val.split(',') }, description: "Filter by a comma separated list of integers."
       else
         dsl.optional field, type: klass.param_type(model,field), description: "Filter on #{field} by value."
       end
     end
+
+    custom_filters.each do |filter,details|
+      dsl.optional filter, details
+    end
+
     dsl.optional :filter, type: String, description: "JSON of conditions for query. If you're familiar with ActiveRecord's query conventions you can build more complex filters, e.g. against included child associations, e.g. {\"<association_name>_<parent>\":{\"field\":\"value\"}}"
 
   end
@@ -49,11 +66,18 @@ module IntrospectiveGrape::Filters
       if timestamp_filter(klass,model,field)
         op      = field.ends_with?("_start") ? ">=" : "<="
         records = records.where("#{timestamp_filter(klass,model,field)} #{op} ?", Time.zone.parse(params[field]))
+      elsif model.respond_to?("#{field}=")
+        records = records.send("#{field}=", params[field])
       else
         records = records.where(field => params[field])
       end
     end
 
+    klass.custom_filters.each do |filter,details|
+      records = records.send(filter, params[filter])
+    end
+
+
     if params[:filter].present?
       filters = JSON.parse( params[:filter].delete('\\') )
       filters.each do |key, value|

data/lib/introspective_grape/version.rb

@@ -1,3 +1,3 @@
 module IntrospectiveGrape
-  VERSION = "0.1.9".freeze
+  VERSION = "0.2.0".freeze
 end

data/spec/requests/user_api_spec.rb

@@ -44,7 +44,6 @@ describe Dummy::UserAPI, type: :request do
       response.should be_success
       json.length.should eq 3
       json.map {|j| j['id'] }.should eq user_ids
-
     end
 
     it "should not expose users' encrypted_passwords" do

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: introspective_grape
 version: !ruby/object:Gem::Version
-  version: 0.1.9
+  version: 0.2.0
 platform: ruby
 authors:
 - Josh Buermann
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-09-27 00:00:00.000000000 Z
+date: 2016-10-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails