api_me 0.3.1 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6b1bab29cbafd8eaab2edc45f10f6e1875a3b49d
-  data.tar.gz: 5f542f1dac50766aec5be47c56fb9a819ed11c7d
+  metadata.gz: 92daadad80db70e8aef932f76f51c4588438af3f
+  data.tar.gz: 7a206ff30375d224b053b2c522fe224d130be1f1
 SHA512:
-  metadata.gz: bef770b426760b1c06de0d917ada87a8946be652dedcba3cbdf3d3e13ceb721110fdb17704df8cfc28700021f6fcb3a67bb074fa9e30165e8344ee3f986708d4
-  data.tar.gz: 1134ce12dc9dee16f652d929b76a69dc98f39332efd6d71066b9dc9c48d0c98c1a0692f839519a12ef79fc20615af326be09e4f2d5847d6967f3859bfcac0de6
+  metadata.gz: 900a7acabcbbc6fe0ca576c7f94cb1be4e2acfc4a63d85209dacd78603dae7273aca01e6b8ae8acccdc5a95db43ef057aaef714b651013fc9347c7df864e5a5b
+  data.tar.gz: 09053b626b1c8120569ba25202356db997985e1f79bedc01ae770af1b78d3e5dcc7caca4f9fac2279d14ff9a6406f92e7a5fd48330906d689e7d478bd7d23d0a

data/README.md

@@ -7,6 +7,11 @@ ApiMe
 ### A gem for building RESTful Api resources in Rails
 ApiMe provides a set of generators and base classes to assist with building Restful API's in Ruby on Rails.
 
+### Details
+Api controllers use the fantastic [Pundit](https://github.com/elabs/pundit) gem for authorization and parameter whitelisting, [Active Model Serializers ver 0.8](https://github.com/rails-api/active_model_serializers/tree/0-8-stable) for resource serialization, and [SearchObject](https://github.com/RStankov/SearchObject) for list filtering. The model, filter, serializer, and policy that the controller uses by default can all be overriden, along with other optional parameters.
+
+The primary goal of this gem was to keep things simple so that customization is fairly straight forward through the separating concerns and overrides. Reusing existing libraries was a primary goal during the design, hence the overall simplicity of this gem. We currently use this gem internally at [Inigo](inigo.io) and are committed to its ongoing maintenance.
+
 ### Usage
 `rails g api_me:resource user organization:belongs_to name:string ...`
 
@@ -15,24 +20,84 @@ this generates the following:
 * app/controllers/api/v1/users_controller.rb
 * app/policies/user_policy.rb
 * app/serializers/user_serializer.rb
-* app/models/user.rb
 
-Or
+and also essentially calls:
+* `rails g model user organization:belongs_to name:string ...`
+Which generates the model et al as specified.
 
-users_controller.rb
+users_controller.rb:
 ````rb
 class UsersController < ApplicationController
   include ApiMe
+
+end
+````
+POST (create) and PUT (update) requests are expected to post parameters to the singular underscored name of the model by default (I.E. `{"user": {"name": "Test"}}` for a user model), but this can be overriden by overriding `def params_klass_symbol`, or more in-depth by overriding `def object_params`. If `def object_params` is overriden, parameters are also expected be whitelisted inside of this method.
+
+models/user.rb:
+````rb
+# Standard Rails generator used
+class User < ActiveRecord::Base
+  belongs_to :organization
+end
+````
+
+policies/user_policy.rb (See [Pundit](https://github.com/elabs/pundit) for details):
+````rb
+class UserPolicy < ApplicationPolicy
+  # Authorizes what parameters will be whitelisted, see [Pundit](https://github.com/elabs/pundit) for details
+  def permitted_attributes
+    [:id, :organization_id, :name]
+  end
+
+end
+````
+
+serializers/user_serializer.rb (See [Active Model Serializers ver 0.8](https://github.com/rails-api/active_model_serializers/tree/0-8-stable) for details):
+````rb
+class UserSerializer < ActiveModel::Serializer
+  attributes :id, :name, :organization_id
 end
 ````
 
-#### This gem uses the following libraries:
-* Pundit
-* Active Model Serializers (0.8)
+filters/user_filter.rb (See [SearchObject](https://github.com/RStankov/SearchObject) for details):
+````rb
+require 'search_object'
+
+class UserFilter < ApiMe::BaseFilter
+  include ::SearchObject.module #required
+
+  # Add custom filter logic here
+  # Ex:
+  #   option(:search) { |scope, value| scope.where("username LIKE ?", "%#{value}%") }
+end
+````
+The ApiMe::BaseFilter is called if no filter exists for the resource, by default the base filter provides filtering by ids for convenience. I.E a GET to `/api/v1/users?ids%5B%5D=1&ids%5B%5D=3` would return users filtered by ids of 1 and 3. All other filters are expected by default to be located at `params[:filters]` and not at the base level.
+
+### Overrides
+Overriding the default model class, serializer class, filter class, and filter parameter can be done like so:
+
+users_controller.rb:
+````rb
+class UsersController < ApplicationController
+  include ApiMe
+
+  model FakeUser
+  serialzier RealUserSerialzier
+
+  def filter_klass
+    FancyUserFilter
+  end
+
+  def filter_params
+    params[:meta][:filters]
+  end
+end
+````
 
 #### Todo:
-- [ ]  Add the ability to specify resource filters
 - [ ]  Add the ability to specify the api controller path (I.E. app/controllers/api/v2)
+- [ ]  Add the ability to inject the resource route into the routes file in the resource generators
 
 ## License
 Copyright (c) 2014, Api Me is developed and maintained by Sam Clopton, and is released under the open MIT Licence.

data/api_me.gemspec

@@ -22,6 +22,7 @@ Gem::Specification.new do |s|
   s.add_runtime_dependency 'activesupport',            '>= 3.2.0'
   s.add_runtime_dependency 'pundit',                   '~> 0.1'
   s.add_runtime_dependency 'active_model_serializers', '~> 0.8.0'
+  s.add_runtime_dependency 'search_object',            '~> 1.0'
 
   s.add_development_dependency 'combustion',  '~> 0.5.1'
   s.add_development_dependency 'rspec-rails', '~> 3'

data/lib/api_me.rb

@@ -1,18 +1,16 @@
 require 'active_support/concern'
 require 'pundit'
+require 'search_object'
 
 require 'api_me/version'
+require 'api_me/base_filter'
 
 module ApiMe
   extend ActiveSupport::Concern
   include ::Pundit
 
   included do
-
     rescue_from Pundit::NotAuthorizedError, with: :user_not_authorized
-
-    after_action :verify_authorized, except: :index
-    after_action :verify_policy_scoped, only: :index
   end
 
   module ClassMethods
@@ -42,6 +40,10 @@ module ApiMe
       end
     end
 
+    def filter_klass
+      @filter_klass ||= filter_klass_name.safe_constantize || ::ApiMe::BaseFilter
+    end
+
     def model_klass_name
       @model_klass_name ||= name.demodulize.sub(/Controller$/, '').singularize
     end
@@ -50,14 +52,24 @@ module ApiMe
       @serializer_klass_name ||= "#{name.demodulize.sub(/Controller$/, '').singularize}Serializer"
     end
 
-    def params_klass_symbol
-      model_klass.name.demodulize.underscore.to_sym
+    def filter_klass_name
+      @filter_klass_name ||= "#{name.demodulize.sub(/Controller$/, '').singularize}Filter"
     end
   end
 
+  # Currently merge params[:ids] in filters hash
+  # to support common use case of filtering ids using
+  # the top level ids array param. Would eventually like
+  # to move to support the jsonapi.org standard closer.
   def index
+    ids_filter_hash = params[:ids] ? {ids: params[:ids]} : {}
     @scoped_objects = policy_scope(model_klass.all)
-    render json: @scoped_objects, each_serializer: serializer_klass
+    @filter_objects = filter_klass.new({
+        scope: @scoped_objects,
+        filters: (filter_params || {}).merge(ids_filter_hash)
+    })
+
+    render json: @filter_objects.results, each_serializer: serializer_klass
   end
 
   def show
@@ -114,10 +126,6 @@ module ApiMe
     render json: payload, status: 403
   end
 
-  def params_klass_symbol
-    self.class.params_klass_symbol
-  end
-
   def model_klass
     self.class.model_klass
   end
@@ -125,4 +133,16 @@ module ApiMe
   def serializer_klass
     self.class.serializer_klass
   end
+
+  def filter_klass
+    self.class.filter_klass
+  end
+
+  def params_klass_symbol
+    model_klass.name.demodulize.underscore.to_sym
+  end
+
+  def filter_params
+    params[:filters]
+  end
 end

data/lib/api_me/base_filter.rb

@@ -0,0 +1,7 @@
+module ApiMe
+  class BaseFilter
+    include SearchObject.module
+
+    option(:ids) { |scope, value| scope.where("id" => value) }
+  end
+end

data/lib/api_me/version.rb

@@ -1,3 +1,3 @@
 module ApiMe
-  VERSION = '0.3.1'
+  VERSION = '0.3.2'
 end

data/lib/generators/api_me/controller/USAGE

@@ -2,7 +2,7 @@ Description:
     This generator generates an api controller that inherits from ApiMe::BaseController
 
 Example:
-    rails generate api_controller foo_bar foo:references{polymorphic} bar:belongs_to name description
+    rails generate api_me:controller foo_bar foo:references{polymorphic} bar:belongs_to name description
 
     This will create:
         app/controllers/api/v1/foo_bars_controller.rb

data/lib/generators/api_me/filter/filter_generator.rb

@@ -0,0 +1,58 @@
+module ApiMe
+  module Generators
+    class FilterGenerator < ::Rails::Generators::NamedBase
+      source_root File.expand_path('../templates', __FILE__)
+      check_class_collision suffix: 'Filter'
+
+      argument :attributes, type: :array, default: [], banner: 'field field'
+
+      class_option :parent, type: :string, desc: 'The parent class for the generated filter'
+
+      def create_api_filter_file
+        template 'filter.rb', File.join('app/filters', "#{singular_name}_filter.rb")
+      end
+
+      def filter_class_name
+        "#{class_name}Filter"
+      end
+
+      def attributes_names
+        attributes.select { |attr| !attr.reference? }.map { |a| a.name.to_sym }
+      end
+
+      def associations
+        attributes.select(&:reference?)
+      end
+
+      def nonpolymorphic_attribute_names
+        associations.select { |attr| attr.type.in?([:belongs_to, :references]) }
+                    .reject { |attr| attr.attr_options.fetch(:polymorphic, false) }
+                    .map { |attr| "#{attr.name}_id".to_sym }
+      end
+
+      def polymorphic_attribute_names
+        associations.select { |attr| attr.type.in?([:belongs_to, :references]) }
+                    .select { |attr| attr.attr_options.fetch(:polymorphic, false) }
+                    .map { |attr| ["#{attr.name}_id".to_sym, "#{attr.name}_type".to_sym] }.flatten
+      end
+
+      def association_attribute_names
+        nonpolymorphic_attribute_names + (polymorphic_attribute_names)
+      end
+
+      def strong_parameters
+        (attributes_names + association_attribute_names).map(&:inspect).join(', ')
+      end
+
+      def parent_class_name
+        if options[:parent]
+          options[:parent]
+        else
+          'ApiMe::BaseFilter'
+        end
+      end
+
+      hook_for :test_framework
+    end
+  end
+end

data/lib/generators/api_me/filter/templates/filter.rb

@@ -0,0 +1,9 @@
+<% module_namespacing do -%>
+class <%= filter_class_name %> < <%= parent_class_name %>
+  include ::SearchObject.module #required
+  
+  # Add custom filter logic here
+  # Ex:
+  #   option(:search) { |scope, value| scope.where("username LIKE ?", "%#{value}%") }
+end
+<% end -%>

data/lib/generators/api_me/policy/USAGE

@@ -2,7 +2,7 @@ Description:
     Explain the generator
 
 Example:
-    rails generate api_policy Thing
+    rails generate api_me:policy Thing
 
     This will create:
         what/will/it/create

data/spec/acceptance/api/v1/posts_spec.rb

@@ -0,0 +1,33 @@
+require 'spec_helper'
+
+describe 'Users API' do
+  it 'sends the list of posts using the default filter' do
+    posts = [
+      Post.create(name: "test"),
+      Post.create(name: "test 2")
+    ]
+
+    get '/api/v1/posts'
+
+    expect(last_response.status).to eq(200)
+    json = JSON.parse(last_response.body)
+
+    expect(json['posts'].length).to eq(2)
+  end
+
+  it 'sends posts filtered by ids' do
+    posts = [
+      Post.create(name: "test"),
+      Post.create(name: "test 2"),
+      Post.create(name: "test 3")
+    ]
+
+    get '/api/v1/posts?ids%5B%5D=' + posts[0].id.to_s +
+        '&ids%5B%5D=' + posts[2].id.to_s
+
+    expect(last_response.status).to eq(200)
+    json = JSON.parse(last_response.body)
+
+    expect(json['posts'].length).to eq(2)
+  end
+end

data/spec/acceptance/api/v1/users_spec.rb

@@ -62,4 +62,19 @@ describe 'Users API' do
     expect(last_response.status).to eq(204)
     expect(does_user_exist).to eq(false)
   end
+
+  it 'sends a filtered list of users' do
+    users = [
+      User.create(username: 'Test'),
+      User.create(username: 'Demo'),
+      User.create(username: 'Test 2')
+    ]
+
+    get '/api/v1/users?filters%5Bsearch%5D=Test'
+
+    expect(last_response.status).to eq(200)
+    json = JSON.parse(last_response.body)
+
+    expect(json['users'].length).to eq(2)
+  end
 end

data/spec/internal/app/controllers/api/v1/posts_controller.rb

@@ -0,0 +1,3 @@
+class Api::V1::PostsController < ApplicationController
+  include ApiMe
+end

data/spec/internal/app/filters/user_filter.rb

@@ -0,0 +1,7 @@
+require 'search_object'
+
+class UserFilter < ApiMe::BaseFilter
+  include ::SearchObject.module
+
+  option(:search) { |scope, value| scope.where("username LIKE ?", "%#{value}%") }
+end

data/spec/internal/app/models/post.rb

@@ -0,0 +1,2 @@
+class Post < ActiveRecord::Base
+end

data/spec/internal/app/policies/post_policy.rb

@@ -0,0 +1,4 @@
+class PostPolicy < ApplicationPolicy
+  class Scope < ApplicationPolicy::Scope
+  end
+end

data/spec/internal/app/serializers/post_serializer.rb

@@ -0,0 +1,3 @@
+class PostSerializer < ActiveModel::Serializer
+  attributes :name
+end

data/spec/internal/config/routes.rb

@@ -2,6 +2,7 @@ Rails.application.routes.draw do
   namespace :api do
     namespace :v1 do
       resources :users
+      resources :posts
       resources :fails
       resources :multi_word_resources
     end

data/spec/internal/db/schema.rb

@@ -3,4 +3,9 @@ ActiveRecord::Schema.define do
     t.string :username
     t.timestamps
   end
+
+  create_table :posts, force: true do |t|
+    t.string :name
+    t.timestamps
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: api_me
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.3.2
 platform: ruby
 authors:
 - Sam Clopton
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-11-07 00:00:00.000000000 Z
+date: 2014-11-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -66,6 +66,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 0.8.0
+- !ruby/object:Gem::Dependency
+  name: search_object
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
 - !ruby/object:Gem::Dependency
   name: combustion
   requirement: !ruby/object:Gem::Requirement
@@ -154,27 +168,37 @@ files:
 - api_me.gemspec
 - config.ru
 - lib/api_me.rb
+- lib/api_me/base_filter.rb
 - lib/api_me/version.rb
 - lib/generators/api_me/controller/USAGE
 - lib/generators/api_me/controller/controller_generator.rb
 - lib/generators/api_me/controller/templates/controller.rb
+- lib/generators/api_me/filter/USAGE
+- lib/generators/api_me/filter/filter_generator.rb
+- lib/generators/api_me/filter/templates/filter.rb
 - lib/generators/api_me/policy/USAGE
 - lib/generators/api_me/policy/policy_generator.rb
 - lib/generators/api_me/policy/templates/policy.rb
 - lib/generators/api_me/resource/USAGE
 - lib/generators/api_me/resource/resource_generator.rb
 - spec/acceptance/api/v1/fails_spec.rb
+- spec/acceptance/api/v1/posts_spec.rb
 - spec/acceptance/api/v1/users_spec.rb
 - spec/acceptance/multi_word_resource_spec.rb
 - spec/internal/app/controllers/api/v1/fails_controller.rb
 - spec/internal/app/controllers/api/v1/multi_word_resources_controller.rb
+- spec/internal/app/controllers/api/v1/posts_controller.rb
 - spec/internal/app/controllers/api/v1/users_controller.rb
 - spec/internal/app/controllers/application_controller.rb
+- spec/internal/app/filters/user_filter.rb
+- spec/internal/app/models/post.rb
 - spec/internal/app/models/test_model.rb
 - spec/internal/app/models/user.rb
 - spec/internal/app/policies/application_policy.rb
+- spec/internal/app/policies/post_policy.rb
 - spec/internal/app/policies/test_model_policy.rb
 - spec/internal/app/policies/user_policy.rb
+- spec/internal/app/serializers/post_serializer.rb
 - spec/internal/app/serializers/test_model_serializer.rb
 - spec/internal/app/serializers/user_serializer.rb
 - spec/internal/config/database.yml