api_presenter 0.4.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: e25ab86494a94eea804adefb23b99ead9f1234ef
-  data.tar.gz: d45fb6fa6067af2e1eddb2853708656c995ef900
+SHA256:
+  metadata.gz: b9b45f72f53a0f0d6ddf34ba993ec0a6f5cbcd6fd7f2b8b2436d5963d2f50296
+  data.tar.gz: 48d1037e5b1af28c574b421996e9350e119fddc89024aeb7bbb7b059f9cec8e7
 SHA512:
-  metadata.gz: ee2a0673296a1b8329423c8fe041671634f367dc49a9d06e8ecf4da87aa9f3f66d0ef43a9c208c497d2befef89874271ce8d185017d0d53321e87eb3f304558d
-  data.tar.gz: 1107b80b1fa2b9d4a94e2b011f730b95d10a6e42a03143459184655930de6084dc182359ca60b757527d7d0b804296a6e18792dde4192c3e227550a83b3dc9a5
+  metadata.gz: 696d7eb80f9327f58f44ab02adfdc14da7a204fa4ae18ac360bde122f5953b55fc986cfa8489fa69c0f4372f3de1d525047512b3e4344b68e35fe3e1fb0f8c54
+  data.tar.gz: 1df07f9a061b26b111c00ce52b57a6f89911b914fd787e9e008254da9bf5d01c350ea29af57ea948dd5836b6e2723d979ab946053fd842fb973cbe6c574022e5

data/.travis.yml

@@ -1,4 +1,4 @@
 language: ruby
 rvm:
   - 2.2.2
-before_install: gem install bundler -v 1.10.3
+before_install: gem install bundler -v 2.2.12

data/CHANGELOG.md

@@ -1,3 +1,11 @@
+## 0.4.1 (2016-11-10)
+
+Bug fix: include `ApplicationApiPresenter` in presenter lookup path.
+
+## 0.4.0 (2016-11-10)
+
+Adds presenter generator.
+
 ## 0.3.0 (2016-11-09)
 
 Adds configuration options and generator.

data/README.md

@@ -1,13 +1,11 @@
 # ApiPresenter
 
-A much longer readme is coming, including best practices and cautions, but in the meantime lets keep it simple...
+REST APIs provide a concise and conventional means of retrieving resources for a client. But in the real world, clients often have additional data requirements beyond the specifically requested resource(s):
 
-When creating RESTful APIs for web or mobile clients, there are a couple of desirable endpoint behaviors:
+1. Current user permissions for the returned records, so that the client can intelligently draw its UI (ex: edit/delete buttons).
+2. Associated data, to mitigate total number of requests (ex: return authors with posts).
 
-* 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.
+ApiPresenter provides both of these things, plus a bit more.
 
 ## Installation
 
@@ -27,7 +25,7 @@ Or install it yourself as:
 
 ## Usage
 
-We'll use a simple blog as the usage example for this gem. The blog has the following model structure:
+ApiPresenter is well suited to large, relational systems. We'll use a blog as the usage example for this gem. The blog has the following model structure:
 
 ```ruby
 class Category < ActiveRecord::Base
@@ -52,22 +50,22 @@ class User < ActiveRecord::Base
 end
 ```
 
-When requesting posts from the API, a client may also want any or all of the posts' categories, sub categories, and users. It may also want the current user's policies for the posts to generate correct UI.
+Usage examples will be in the context of requesting posts as the primary collection.
 
 ### 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 configuration options coming soon.
+Generate your configuration file. Currently, ApiPresenter allows customization of querystring parameter names for including policies and associated resources (see below). More configuration options to come.
 
 ### 1. Create your Presenter
 
-Using the supplied generator, generate a presenter class for your ActiveRecord model. The generator will also generate a convenient `ApplicationApiPresenter` class for centralized methods.
+Generate a presenter class for your ActiveRecord model. The generator will also ensure the presence of an `ApplicationApiPresenter` base class for centralized methods.
 
 `rails g api_presenter:presenter post`
 
 ```ruby
-class PostPresenter < ApiApplicationController
+class PostPresenter < ApplicationApiPresenter
   def associations_map
     {
       categories:     { associations: { sub_category: :category } },
@@ -86,21 +84,15 @@ class PostPresenter < ApiApplicationController
 end
 ```
 
-Presenters have three opt-in methods:
+Presenters can define three opt-in methods:
 
-* `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.
+* `associations_map` Associated resources that you would like to be includable with the primary collection. Consists of the model name as key and the 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.
+* `policy_associations` Additional associations 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 from your controller action. The preloads will be performed, and the included collections/policies will be available in the `@presenter` instance variable.
-
-The following configurable 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
+Include the supplied controller concern at your `ApplicationController` level, or on a specific controller. This concern provides the `present` method, which can be called on an `ActiveRecord::Relation`, an array of records, or even a single record (preloading of associated collections is only performed for relations).
 
 ```ruby
 class ApplicationController
@@ -129,17 +121,25 @@ class PostsController < ApplicationController
 end
 ```
 
+Controller params are used to tell the presenter what to load. The default param keys are `count`, `policies`, and `include`:
+
+* `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.
+* `include [String, Array]` A comma-delimited list or array of collection names (camelCase or under_scored) to include with the primary collection.
+
 ### 3. Render the result
 
-How you ultimately render the primary collection and the data produced by ApiPresenter is up to you. `@presenter` has the following properties:
+After calling the `present` method in a controller action, you access your processed collection through the `@presenter` instance variable. How you ultimately render the data produced by ApiPresenter is up to you.
+
+`@presenter` has the following properties:
 
 * `collection [Array<ActiveRecord::Base>]` The primary collection that was passed into the presenter. Empty if count requested.
 * `total_count [Integer]` When using Kaminari or another pagination method that defines a `total_count` property, returns unpaginated count. If the primary collection is not an `ActiveRecord::Relation`, simply returns the number of records.
-* `included_collection_names [Array<Symbol>]` Convenience method that returns an array of included collecton model names.
+* `included_collection_names [Array<Symbol>]` Convenience method that returns an array of included collection model names.
 * `included_collections [Hash]` A hash of included collections, consisting of the model name and corresponding records.
 * `policies [Array<Hash>]` An array of resolved policies for the primary collection.
 
-Here's an example of how you might render this using JBduiler:
+Here's an example of how you might render your data using JBduiler:
 
 ### api/posts/index.json.jbuilder
 
@@ -176,7 +176,7 @@ end
 
 ### 4. Output
 
-Using the code above, our call to `GET /posts` would result in the following JSON:
+Using the code above, our call to `GET /posts?include=categories,subCategories,users&policies=true` would result in the following JSON:
 
 ```json
 {
@@ -206,7 +206,7 @@ Using the code above, our call to `GET /posts` would result in the following JSO
 }
 ```
 
-And similarily, for `GET /posts/1`:
+And similarily, for `GET /posts/1?include=categories,subCategories,users&policies=true`:
 
 ```json
 {
@@ -234,12 +234,12 @@ And similarily, for `GET /posts/1`:
 
 ### Conditional includes
 
-There are a number of ways you can conditionally include resources, depending, for insatnce, on user type.
+There are a number of ways you can conditionally include resources, depending, for instance, on user type.
 
 #### Add conditions inside `associations_map` method
 
 ```ruby
-class PostPresenter < ApiPresenter::Base
+class PostPresenter < ApiApplicationPresenter
   def associations_map
     current_user.admin? ? admin_associations_map : user_associations_map
   end
@@ -265,7 +265,7 @@ end
 
 #### Use `condition` property within `association_map` definition
 
-Via inline string:
+##### Via inline string
 
 ```ruby
 class PostPresenter < ApiPresenter::Base
@@ -279,7 +279,7 @@ class PostPresenter < ApiPresenter::Base
 end
 ```
 
-Via method call:
+##### Via method call
 
 ```ruby
 class PostPresenter < ApiPresenter::Base
@@ -311,12 +311,10 @@ end
 
 ## TODO
 
-* More doc
 * Decouple from Pundit
 * 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/api_presenter.gemspec

@@ -19,7 +19,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency "activesupport", ">= 3.0.0"
   spec.add_dependency "pundit"
   spec.add_development_dependency "activerecord", ">= 4.2.3"
-  spec.add_development_dependency "bundler", "~> 1.10"
+  spec.add_development_dependency "bundler", "~> 2.2.12"
   spec.add_development_dependency "rake", "~> 10.0"
   spec.add_development_dependency "rspec"
   spec.add_development_dependency "sqlite3"

data/lib/api_presenter/base.rb

@@ -14,8 +14,8 @@ module ApiPresenter
     #
     # @return [ApiPresenter::Base]
     #
-    def self.call(**kwargs)
-      new(kwargs).call
+    def self.call(current_user: nil, relation:, params: {})
+      new(current_user: current_user, relation: relation, params: params).call
     end
 
     # @param current_user [User]                          Optional. current_user context.

data/lib/api_presenter/version.rb

@@ -1,3 +1,3 @@
 module ApiPresenter
-  VERSION = "0.4.1"
+  VERSION = "1.0.0"
 end

metadata

@@ -1,15 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: api_presenter
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 1.0.0
 platform: ruby
 authors:
 - Yuval Kordov
 - Little Blimp
-autorequire: 
+autorequire:
 bindir: exe
 cert_chain: []
-date: 2016-11-10 00:00:00.000000000 Z
+date: 2022-06-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -59,14 +59,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.10'
+        version: 2.2.12
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.10'
+        version: 2.2.12
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -148,7 +148,7 @@ homepage: http://github.com/uberllama/api_presenter
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -163,9 +163,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.4.6
-signing_key: 
+rubygems_version: 3.0.9
+signing_key:
 specification_version: 4
 summary: Return associations and policies with API responses
 test_files: []