api_presenter 0.2.4 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2a3e0a34d5d50f902760195ffd58a409d3231a15
-  data.tar.gz: 8a4261472f7ba030c7ff72e2bed5d9c3171b98d6
+  metadata.gz: 9e411385a8bd85df6bc3efe9f1ec418d5608f26f
+  data.tar.gz: a7da14574b9aabd4501edafd1555feb16246ff05
 SHA512:
-  metadata.gz: 3e3491e2c26ac8affb10ba11eaeef277be47b4b9666f205a6c9f5a07da5178b204ffcc28961e10df10811abb6a98ff5cc0e0968e0d213911f07f96d1094a94fa
-  data.tar.gz: e426cce2a716fc7cdcb4e5066cd9b9a51509a5c339886031c27159fe0a6698c07f08f107f939cd6c0a071637bd7f4ee942f61e2876d139757f42383e157ed367
+  metadata.gz: 810bfdd0b1932949b0d6984ac1b0935467de3e5d27858f05890b906447aa2124fc0beee23c0cf95a5d624df168a2e20eb2b38d567650c685e291a905724859a4
+  data.tar.gz: 29e3508ed61708ae44f7f4470e9687a0131d0e56a991b307ba1519ebd6b6755d92ff7903a26f7af6d25b6bd78d8f62b4a742332439d5b9b758f6bfc08e65f583

data/README.md

@@ -2,10 +2,10 @@
 
 A much longer readme is coming, including best practices and cautions, but in the meantime lets keep it simple...
 
-When creating RESTful APIs for web or mobile clients, there are a couple of common use cases that have emerged:
+When creating RESTful APIs for web or mobile clients, there are a couple of desirable endpoint behaviors:
 
-* Allow inclusion of associated data to mitigate number of requests
 * Include permissions so that the client can intelligently draw its UI (ex: edit/delete buttons), while maintaining a single source of truth
+* Allow inclusion of associated data to mitigate total number of requests
 
 ApiPresenter does both of these things, plus a bit more.
 
@@ -52,7 +52,11 @@ class User < ActiveRecord::Base
 end
 ```
 
-When clients request posts (the primary collection), they may want any or all of the above data for those posts.
+### 0. Generate config file
+
+`rails g api_presenter:config`
+
+Generates a configuration file that allows you to override the default querystring params used by the `presenter` concern. More to come.
 
 ### 1. Create your Presenter
 
@@ -78,13 +82,19 @@ end
 
 Presenters can define up to three methods:
 
-* `associations_map` The includable resources for the ActiveRecord model (`Post`, in this case). Consists of the model name as key and traversal required to preload/load them. In most cases, the value of `associations` will correspond directly to associations on the primary model.
-* `policy_methods` A list of Pundit policy methods to resolve for the primary collection.
+* `associations_map` The business-dictated includable resources for the ActiveRecord model (`Post`, in this case). Consists of the model name as key and traversal required to preload/load them. In most cases, the value of `associations` will correspond directly to associations on the primary model.
+* `policy_methods` A list of Pundit policy methods to resolve for the primary collection if policies are requested.
 * `policy_associations` Additional records to preload in order to optimize policies that must traverse asscoiations.
 
 ### 2. Enable your controllers
 
-Your presentable collection can be an `ActiveRecord::Relation`, an array of records, or even a single record. Just call `present` on it. The preloads will be performed, and the included collections/policies will be available in the `@presenter` instance variable.
+Your presentable collection can be an `ActiveRecord::Relation`, an array of records, or even a single record. Just call `present` on it from your controller action. The preloads will be performed, and the included collections/policies will be available in the `@presenter` instance variable.
+
+The following querystring params are used by the supplied controller concern's `present` method:
+
+* `count [Boolean]` Pass true if you just want a count of the primary collection
+* `policies [Boolean]` Pass true if you want to resolve policies for the primary collection records
+* `include [String, Array]` A comma-delimited list or array of collection names (camelCase or under_scored) to include with the primary collection
 
 ```ruby
 class ApplicationController
@@ -92,11 +102,18 @@ class ApplicationController
 end
 
 class PostsController < ApplicationController
+
+  # @example
+  #   GET /posts?include=categories,subCategories,users&policies=true
+  #
   def index
     posts = PostQuery.records(current_user, params)
     present posts
   end
 
+  # @example
+  #   GET /posts/:id?include=categories,subCategories,users&policies=true
+  #
   def show
     post = Post.find(params[:id])
     present post
@@ -134,13 +151,6 @@ end
 json.partial!("api/shared/included_collections_and_meta", presenter: @presenter)
 ```
 
-```ruby
-json.posts(@presenter.collection) do |post|
-  json.partial!(post)
-end
-json.partial!("api/shared/included_collections_and_meta", presenter: @presenter)
-```
-
 ### api/shared/included_collections_and_meta
 
 ```ruby
@@ -156,6 +166,62 @@ json.meta do
 end
 ```
 
+### 4. Output
+
+Using the code above, our call to `GET /posts` would result in the following JSON:
+
+```json
+{
+  "posts": [
+    { "id": 1, "sub_category": 1, "creator_id": 1, "publisher_id": 2, "body": "Lorem dim sum", "published": true },
+    { "id": 2, "sub_category": 2, "creator_id": 3, "publisher_id": null, "body": "Lorem dim sum", "published": false }
+  ],
+  "categories": [
+    { "id": 1, "name": "Animals" }
+  ],
+  "sub_categories": [
+    { "id": 1, "category_id": 1, "name": "Lemurs" },
+    { "id": 2, "category_id": 1, "name": "Anteaters" }
+  ],
+  "users": [
+    { "id": 1, "name": "Dora" },
+    { "id": 2, "name": "Boots" },
+    { "id": 3, "name": "Backpack" }
+  ],
+  "meta": {
+    "total_count": 2,
+    "policies": [
+      { "post_id": 1, "update": true, "destroy": false },
+      { "post_id": 2, "update": true, "destroy": true }
+    ]
+  }
+}
+```
+
+And similarily, for `GET /posts/1`:
+
+```json
+{
+  "post": { "id": 1, "sub_category": 1, "creator_id": 1, "publisher_id": 2, "body": "Lorem dim sum", "published": true },
+  "categories": [
+    { "id": 1, "name": "Animals" }
+  ],
+  "sub_categories": [
+    { "id": 1, "category_id": 1, "name": "Lemurs" }
+  ],
+  "users": [
+    { "id": 1, "name": "Dora" },
+    { "id": 2, "name": "Boots" }
+  ],
+  "meta": {
+    "total_count": 1,
+    "policies": [
+      { "post_id": 1, "update": true, "destroy": false }
+    ]
+  }
+}
+```
+
 ## Advanced Usage
 
 ### Conditional includes
@@ -242,6 +308,7 @@ end
 * Make index policy checking on includes optional
 * Allow custom collection names
 * Add test helper to assert presenter was called for a given controller action
+* Add presenter generator
 
 ## Development
 

data/lib/api_presenter.rb

@@ -1,7 +1,9 @@
 require 'pundit'
+
 module ApiPresenter; end
 
 require 'api_presenter/base'
+require 'api_presenter/configuration'
 require 'api_presenter/concerns/presentable'
 require 'api_presenter/parsers/parse_include_params'
 require 'api_presenter/resolvers/base'

data/lib/api_presenter/base.rb

@@ -80,7 +80,7 @@ module ApiPresenter
     # @return [Array<Symbol>]
     #
     def included_collection_names
-      @included_collection_names ||= Parsers::ParseIncludeParams.call(params[:include])
+      @included_collection_names ||= Parsers::ParseIncludeParams.call(params[ApiPresenter.configuration.include_param])
     end
 
     # Map of included collection names and loaded record
@@ -172,11 +172,11 @@ module ApiPresenter
     private
 
     def count_only?
-      @count_only ||= !!params[:count]
+      @count_only ||= !!params[ApiPresenter.configuration.count_param]
     end
 
     def resolve_policies?
-      @resolve_policies ||= current_user && !!params[:policies]
+      @resolve_policies ||= current_user && !!params[ApiPresenter.configuration.policies_param]
     end
 
     def resolve_included_collctions?

data/lib/api_presenter/configuration.rb

@@ -0,0 +1,43 @@
+module ApiPresenter
+  class Configuration
+    # Querystring param key that determines whether or not to just produce a total count
+    #
+    # @return [Symbol]
+    #
+    attr_accessor :count_param
+
+    # Querystring param key containing the included collection names
+    #
+    # @return [Symbol]
+    #
+    attr_accessor :include_param
+
+    # Querystring param key that determines whether or not to resolve policies for primary collection
+    #
+    # @return [Symbol]
+    #
+    attr_accessor :policies_param
+
+    def initialize
+      @count_param    = :count
+      @include_param  = :include
+      @policies_param = :policies
+    end
+  end
+
+  # @return [ApiPresenter::Configuration] ApiPresenter's current configuration
+  def self.configuration
+    @configuration ||= Configuration.new
+  end
+
+  # Set ApiPresenter configuration
+  #
+  # @example
+  #   ApiPresenter.configure do |config|
+  #     config.include_param = :includes
+  #   end
+  #
+  def self.configure
+    yield configuration
+  end
+end

data/lib/api_presenter/version.rb

@@ -1,3 +1,3 @@
 module ApiPresenter
-  VERSION = "0.2.4"
+  VERSION = "0.3.0"
 end

data/lib/generators/api_presenter/config/USAGE

@@ -0,0 +1 @@
+Creates configuration file

data/lib/generators/api_presenter/config/config_generator.rb

@@ -0,0 +1,11 @@
+module ApiPresenter
+  module Generators
+    class ConfigGenerator < Rails::Generators::Base
+      source_root File.expand_path('../templates', __FILE__)
+
+      def copy_config_file
+        copy_file 'api_presenter_config.rb', 'config/initializers/api_presenter_config.rb'
+      end
+    end
+  end
+end

data/lib/generators/api_presenter/config/templates/api_presenter_config.rb

@@ -0,0 +1,5 @@
+ApiPresenter.configure do |config|
+  # config.count_param = :count
+  # config.include_param = :include
+  # config.policies_param = :policies
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: api_presenter
 version: !ruby/object:Gem::Version
-  version: 0.2.4
+  version: 0.3.0
 platform: ruby
 authors:
 - Yuval Kordov
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-11-07 00:00:00.000000000 Z
+date: 2016-11-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -131,11 +131,15 @@ files:
 - lib/api_presenter.rb
 - lib/api_presenter/base.rb
 - lib/api_presenter/concerns/presentable.rb
+- lib/api_presenter/configuration.rb
 - lib/api_presenter/parsers/parse_include_params.rb
 - lib/api_presenter/resolvers/base.rb
 - lib/api_presenter/resolvers/included_collections_resolver.rb
 - lib/api_presenter/resolvers/policies_resolver.rb
 - lib/api_presenter/version.rb
+- lib/generators/api_presenter/config/USAGE
+- lib/generators/api_presenter/config/config_generator.rb
+- lib/generators/api_presenter/config/templates/api_presenter_config.rb
 homepage: http://github.com/uberllama/api_presenter
 licenses:
 - MIT