jsonapi-utils 0.5.1 → 0.5.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d5fa572a99867ebcee2a95e424b1f249c44603fd
-  data.tar.gz: a7859fa30c45aff2cb66e43bce219cc691114310
+  metadata.gz: 95cb09b9a0147e9a991c8ac9b07cea55092560ab
+  data.tar.gz: a26c53529ce6737659dd75a1ae5f70f223317522
 SHA512:
-  metadata.gz: 6351e38706a14d05e137f0daf257a44f98f3140eb4edc3b80306666b88581df8d069cdad8e264dce682d6c255a44c2b6d22c8a6188855240a31c43a3c91b23dc
-  data.tar.gz: fd1fae5c0b4d81d21f52688ad5e44d1e92c3bb0302bcc6346bedf637b78db7c5e8165f85230d5559b5e1ca1e85f5b449c09362ff9d9fd425b7ed080cc617c89b
+  metadata.gz: 90bfc9584d1bca838113bd148dafff85cd31507f22b17279e87c544eed151a2ce68eaa2cbede848df4e95c0aa292cec590df7118ea5847a2f608891eb87483d2
+  data.tar.gz: ae340b7a231721a3505c67a8146bcaae2c03ba2a33a04dfa203f199f2839e49e6bffb826e314b83b782bb768947921e9675ba2d7ca5019d3e66c8551725e4931

data/README.md

@@ -25,7 +25,7 @@ end
 ## Table of Contents
 
 * [Installation](#installation)
-* [How does it work?](#how-does-it-work)
+* [Why JSONAPI::Utils?](#why-jsonapiutils)
 * [Usage](#usage)
   * [Response](#response)
     * [Renders](#renders)
@@ -53,19 +53,19 @@ end
 
 Support:
 
-* Ruby 2.x with Rails 4.x
+* Ruby 1.9+ with Rails 4
 * Ruby 2.3+ with Rails 5
 
-For Rails 4.x add this to your application's Gemfile:
+For Rails 4 add this to your application's Gemfile:
 
 ```ruby
-gem 'jsonapi-utils', '~> 0.4.8'
+gem 'jsonapi-utils', '~> 0.4.9'
 ```
 
-For Rails 5, specify the `0.5.x` version in the Gemfile:
+For Rails 5:
 
 ```ruby
-gem 'jsonapi-utils', '0.5.1'
+gem 'jsonapi-utils', '~> 0.5.2'
 ```
 
 And then execute:
@@ -74,11 +74,11 @@ And then execute:
 $ bundle
 ```
 
-## How does it work?
+## Why JSONAPI::Utils?
 
-One of the main motivations behind `JSONAPI::Utils` is to keep things explicit in controllers so that developers can easily understand and maintain code. Unlike `JSONAPI::Resources` (JR), JU doesn't care about controller operations – what happens with resources within actions – dealing only with the request validation and response rendering and providing some useful helpers. This way developers can decide how to actually operate their actions (service objects, interactors etc).
+One of the main motivations behind `JSONAPI::Utils` is to keep things explicit in controllers (no hidden actions :-) so that developers can easily understand and maintain their code. 
 
-In both layers (request and response) JU communicates with some JR's objects in order to validate requests and render responses properly.
+Unlike `JSONAPI::Resources` (JR), JU doesn't care about how you will operate your controller actions. The gem deals only with the request validation and response rendering (via JR's objects) and provides a set of helpers (renders, formatters etc) along the way. Thus developers can decide how to actually operate their actions: service objects, interactors etc.
 
 ## Usage
 
@@ -93,7 +93,7 @@ JU brings two main renders to the game, working pretty much the same way as Rail
 
 **jsonapi_render**
 
-It takes the arguments and generates a JSON API-compliant response.
+It renders a JSON API-compliant response.
 
 ```ruby
 # app/controllers/users_controller.rb
@@ -138,7 +138,7 @@ jsonapi_render json: { data: [{ id: 1, first_name: 'Tiago' }, { id: 2, first_nam
 
 **jsonapi_render_errors**
 
-It takes arguments and generates a JSON API-compliant error response.
+It renders a JSON API-compliant error response.
 
 ```ruby
 # app/controllers/users_controller.rb
@@ -171,7 +171,7 @@ jsonapi_render_errors json: errors, status: :unprocessable_entity
 
 #### Formatters
 
-In the backstage those are the guys which actually parse ActiveRecord/Hash objects and build a new Hash compliant with JSON API. They can be called anywhere in controllers being very useful if you need to do some work with the response's body before rendering the response.
+In the backstage these are the guys which actually parse the ActiveRecord/Hash object to build a new Hash compliant with JSON API's specs. Formatters can be called anywhere in controllers being very useful if you need to do some work with the response's body before rendering the actual response.
 
 > Note: the resulting Hash from those methods can not be passed as argument to `JSONAPI::Utils#jsonapi_render` or  `JSONAPI::Utils#jsonapi_render_error`, instead it needs to be rendered by the usual `ActionController#render`.
 
@@ -193,14 +193,35 @@ Arguments:
 
 #### Paginators
 
-If you are rendering a collection of hashes, you'll need to implement the `#pagination_range` method, which returns a range for your resources. For example:
+Pagination works out of the box on JU, you just need to decide which kind of paginator you'd like to use.
+
+It's really easy to work with pagination on JU, actually it's just a matter of chosing the [paginator you wish](http://jsonapi-resources.com/v0.8/guide/configuration.html#Defaults) in your JR's config file:
+
+```ruby
+# config/initializers/jsonapi_resources.rb
+JSONAPI.configure do |config|
+  # :none, :offset, :paged, or a custom paginator name
+  config.default_paginator = :paged
+
+  # Output pagination links at top level
+  config.top_level_links_include_pagination = true
+  
+  # Default sizes
+  config.default_page_size = 70
+  config.maximum_page_size = 100
+end
+```
+
+As you may have noticed above, it's possible to use custom paginators. In order to create your own paginator your just need to define a class which inherits from `JSONAPI::Paginator` and implements the `#pagination_range` method which in turn must return the range to be applied over the resulting collection.
+
+For example, if you would like to paginate over a collection of hashes, you may implement the `#pagination_range` method as below:
 
 ```ruby
 class CustomPaginator < JSONAPI::Paginator
   def pagination_range(page_params)
     offset = page_params['offset']
     limit  = JSONAPI.configuration.default_page_size
-    offset..offset + limit - 1
+    offset..offset + limit - 1 # resulting range
   end
 ```
 
@@ -215,7 +236,7 @@ end
 
 ### Request
 
-Before a controller's action gets executed, `JSONAPI::Utils` will validate the request against JSON API specifications as well as evaluating the eventual query string params to check if they match the resource's definition. If something goes wrong during the validation process, JU will render an error response like this examples below:
+Before a controller action gets executed, `JSONAPI::Utils` will validate the request against JSON API's specs as well as evaluating the eventual query string params to check if they match the resource's definition. If something goes wrong during the validation process, JU will render an error response like this examples below:
 
 ```json
 HTTP/1.1 400 Bad Request
@@ -338,48 +359,51 @@ Finally, having inhirited `JSONAPI::Utils` methods from the `BaseController` we
 
 ```ruby
 # app/controllers/users_controller.rb
-# GET /users
-def index
-  users = User.all
-  jsonapi_render json: users
-end
+class UsersController < BaseController
+  # GET /users
+  def index
+    users = User.all
+    jsonapi_render json: users
+  end
 
-# GET /users/:id
-def show
-  user = User.find(params[:id])
-  jsonapi_render json: user
-end
+  # GET /users/:id
+  def show
+    user = User.find(params[:id])
+    jsonapi_render json: user
+  end
 
-# POST /users
-def create
-  user = User.new(resource_params)
-  if user.save
-    jsonapi_render json: user, status: :created
-  else
-    jsonapi_render_errors json: user, status: :unprocessable_entity
+  # POST /users
+  def create
+    user = User.new(resource_params)
+    if user.save
+      jsonapi_render json: user, status: :created
+    else
+      jsonapi_render_errors json: user, status: :unprocessable_entity
+    end
   end
-end
 
-# PATCH /users/:id
-def update
-  user = User.find(params[:id])
-  if user.update(resource_params)
-    jsonapi_render json: user
-  else
-    jsonapi_render_errors json: user, status: :unprocessable_entity
+  # PATCH /users/:id
+  def update
+    user = User.find(params[:id])
+    if user.update(resource_params)
+      jsonapi_render json: user
+    else
+      jsonapi_render_errors json: user, status: :unprocessable_entity
+    end
   end
-end
 
-# DELETE /users/:id
-def destroy
-  User.find(params[:id]).destroy
-  head :no_content
+  # DELETE /users/:id
+  def destroy
+    User.find(params[:id]).destroy
+    head :no_content
+  end
 end
 ```
 
 And:
 
 ```ruby
+# app/controllers/posts_controller.rb
 class PostsController < BaseController
   before_action :load_user, except: :create
 
@@ -393,7 +417,7 @@ class PostsController < BaseController
     jsonapi_render json: @user.posts.find(params[:id])
   end
 
-  # POST /users
+  # POST /posts
   def create
     post = Post.new(post_params)
     if post.save

data/lib/jsonapi/utils/version.rb

@@ -1,5 +1,5 @@
 module JSONAPI
   module Utils
-    VERSION = '0.5.1'.freeze
+    VERSION = '0.5.2'.freeze
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jsonapi-utils
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  version: 0.5.2
 platform: ruby
 authors:
 - Tiago Guedes
@@ -9,22 +9,22 @@ authors:
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-01-20 00:00:00.000000000 Z
+date: 2017-03-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jsonapi-resources
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - '='
       - !ruby/object:Gem::Version
-        version: 0.8.0
+        version: 0.8.3
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - '='
       - !ruby/object:Gem::Version
-        version: 0.8.0
+        version: 0.8.3
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement