jsonapi-utils 0.4.5 → 0.4.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ec04f95554ca59d1117ffa0452646252a5a156c5
-  data.tar.gz: 897fd3e12eceed6338421e6e5b7166afd8279947
+  metadata.gz: c328df382d804f5ae2d625216ac2febd26b952ac
+  data.tar.gz: b13829c6b72e5d4a8fb76fcafcac900916c5d8f6
 SHA512:
-  metadata.gz: 2aa0e5fc2e3c030898bd2287804bb62752523f6f9e6aad6a01c14954d9d8a09dee587117a54cd7463cb9cefedeb5ca2d91bb00548e703b5a99f57eb15e91a97b
-  data.tar.gz: 1136e92931251cce1ad8f652d56ee7555d0da2cbb93c3c4b44b7d33053b9460357b23bf84a9b178cb702e73942d92d9688e61d10ad0cd5e4e4bd80994e2d0a35
+  metadata.gz: 60a974e53b5e40f500bc8a99cba456d21ca7c9c960ff040e91622f35bf40dcae9d6101fa38e93491d79fa96f7ca6e362d0d3857329c1841a06b541903bea2f27
+  data.tar.gz: fc039cfdecd100db6b4d316e5b232734e9b96ec9e77ad8578398e9a542a17828a233a58ee39ea28fbfe673f50f43de783b3fec5fe350145022749662d7c408bf

data/README.md

@@ -13,7 +13,7 @@ JSONAPI::Utils (JU) was built on top of [JSONAPI::Resources](https://github.com/
 Add these lines to your application's Gemfile:
 
 ```ruby
-gem 'jsonapi-utils', '~> 0.4.4'
+gem 'jsonapi-utils', '~> 0.4.5'
 ```
 
 And then execute:
@@ -22,13 +22,29 @@ And then execute:
 $ bundle
 ```
 
-## Response Macros
+## How does it work?
 
-### jsonapi_render
+One of the main motivations behind `JSONAPI::Utils` is to keep things explicit in your controller actions so that developers can easily understand and maintain code. With this principle in mind, JU doesn't care about your controller operations and it deals only with the request and response layers thus letting the developer decides how to actually operate the actions (service objects, interactors or something).
 
-Takes ActiveRecord/Hash objects and generates JSON API-compliant responses.
+In both layers (request and response) JU communicates with some `JSONAPI::Resources`' objects in order to validate requests and render responses properly.
+
+## Usage
+
+### Response
+
+#### Renders
+
+JU brings two main renders to the game, working pretty much the same way as Rails' `ActionController#render` method:
+
+- jsonapi_render
+- jsonapi_render_errors
+
+**jsonapi_render**
+
+It takes the arguments and generates a JSON API-compliant response.
 
 ```ruby
+# app/controllers/users_controller.rb
 # GET /users
 def index
   jsonapi_render json: User.all
@@ -42,14 +58,14 @@ end
 
 Arguments:
 
-  - `json`: ActiveRecord or Hash object to be rendered as JSON document;
+  - `json`: object to be rendered as a JSON document: ActiveRecord object, Hash or Array of Hashes;
   - `status`: HTTP status code (Integer or Symbol). If ommited a status code will be automatically infered;
   - `options`:
     - `resource`: explicitly points the resource to be used in the serialization. By default, JU will select resources by inferencing from controller's name.
     - `count`: explicitly points the total count of records for the request in order to build a proper pagination. By default, JU will count the total number of records.
     - `model`: sets the model reference in cases when `json` is a Hash or a collection of Hashes.
 
-Examples:
+Other examples:
 
 ```ruby
 # Specify a particular HTTP status code
@@ -68,25 +84,103 @@ jsonapi_render json: { data: { id: 1, first_name: 'Tiago' } }, options: { model:
 jsonapi_render json: { data: [{ id: 1, first_name: 'Tiago' }, { id: 2, first_name: 'Doug' }] }, options: { model: User }
 ```
 
-### jsonapi_format
+**jsonapi_render_errors**
 
-In the backstage this is the method that actually parses ActiveRecord/Hash objects and builds a new Hash compliant with JSON API. It can be called anywhere in your controllers being very useful whenever you need to work with a JSON API "serialized" version of your object before rendering it. 
+It takes arguments and generates a JSON API-compliant error response.
 
-Note: because of semantic reasons `JSONAPI::Utils#jsonapi_serialize` was renamed being now just an alias to `JSONAPI::Utils#jsonapi_format`.
+```ruby
+# app/controllers/users_controller.rb
+# POST /users
+  def create
+    user = User.new(user_params)
+    if user.save
+      jsonapi_render json: user, status: :created
+    else
+      jsonapi_render_errors json: user, status: :unprocessable_entity
+    end
+  end
+```
+
+Arguments:
+  - Exception 
+  - `json`: object to be rendered as a JSON document: ActiveRecord, Exception, Array of Hashes or any object which implements the `errors` method;
+  - `status`: HTTP status code (Integer or Symbol). If ommited a status code will be automatically infered from the error body.
+
+Other examples:
 
 ```ruby
+# Render errors from a custom exception:
+jsonapi_render_errors Exceptions::MyCustomError.new(user)
+
+# Render errors from an Array of Hashes:
+errors = [{ id: 'validation', title: 'Something went wrong', code: '100' }]
+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 generate the response body and do some work with it before actually rendering the 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`.
+
+**jsonapi_format**
+
+*Because of semantic reasons `JSONAPI::Utils#jsonapi_serialize` was renamed being now just an alias to `JSONAPI::Utils#jsonapi_format`.*
+
+```ruby
+# app/controllers/users_controller.rb
 def index
-  result = do_some_magic(jsonapi_format(User.all))
-  render json: result
+  body = jsonapi_format(User.all)
+  render json: do_some_magic_with(body)
 end
 ```
 
 Arguments:
-  - It receives the same options as `jsonapi_render`.
+  - First: ActiveRecord object, Hash or Array of Hashes;
+  - Last: Hash of options (same as `JSONAPI::Utils#jsonapi_render`).
 
-## Usage
+### Request
+
+Before your controller's action gets executed JU will validate request against JSON API specifications and eventual query string params against the resource's definitions. If something goes wrong with the request JU will render an error response like this:
+
+```json
+HTTP/1.1 400 Bad Request
+Content-Type: application/vnd.api+json
+
+{
+  "errors": [
+    {
+      "title": "Invalid resource",
+      "detail": "foo is not a valid resource.",
+      "code": "101",
+      "status": "400"
+    },
+    {
+      "title": "Invalid resource",
+      "detail": "foobar is not a valid resource.",
+      "code": "101",
+      "status": "400"
+    },
+    {
+      "title": "Invalid field",
+      "detail": "bar is not a valid relationship of users",
+      "code": "112",
+      "status": "400"
+    }
+  ]
+}
+```
+
+## Full example
+
+In order to start working with JU after installing the gem you simply need to do the following:
 
-Let's say we have a Rails app for a super simple blog.
+1. Include the gem (`include JSONAPI::Utils`) in the target controller or in a `BaseController`;
+2. Define the resources for your models;
+3. Define routes;
+4. Use JU's render methods.
+
+Time for a full example, let's say we have a Rails application for a super simple blog:
 
 ### Models
 
@@ -141,7 +235,7 @@ Rails.application.routes.draw do
 end
 ```
 
-And a base controller to include the features from `jsonapi-resources` and `jsonapi-utils`:
+In our base controller we need to include the `JSONAPI::Utils` module and define some default rendering:
 
 ```ruby
 # app/controllers/base_controller.rb
@@ -152,107 +246,101 @@ class BaseController < JSONAPI::ResourceController
 end
 ```
 
-For this example, let's get focused only on read actions. After including `JSONAPI::Utils` we can use the `jsonapi_render` method
-in order to generate responses which follow the JSON API's standards.
+Finally, having inhirited `JSONAPI::Utils` methods from the `BaseController` we could write our actions as the following:
 
 ```ruby
 # app/controllers/users_controller.rb
-class UsersController < BaseController
-  before_action :load_user, only: [:show]
-
   # GET /users
   def index
-    jsonapi_render json: User.all
+    users = User.all
+    jsonapi_render json: users
   end
 
   # GET /users/:id
   def show
-    jsonapi_render json: @user
+    user = User.find(params[:id])
+    jsonapi_render json: user
+  end
+
+  # POST /users
+  def create
+    user = User.new(user_params)
+    if user.save
+      jsonapi_render json: user, status: :created
+    else
+      jsonapi_render_errors json: user, status: :unprocessable_entity
+    end
+  end
+
+  # PATCH /users/:id
+  def update
+    user = User.find(params[:id])
+    if user.update(user_params)
+      jsonapi_render json: user
+    else
+      jsonapi_render_errors json: user, status: :unprocessable_entity
+    end
+  end
+  
+  # DELETE /users/:id
+  def destroy
+    User.find(params[:id]).destroy
+    head :no_content
   end
 
   private
 
-  def load_user
-    @user = User.find(params[:id])
+  def user_params
+    params.require(:data).require(:attributes).permit(:first_name, :last_name, :admin)
   end
-end
 ```
 
 And:
 
 ```ruby
-# app/controllers/posts_controller.rb
 class PostsController < BaseController
-  before_action :load_user, only: [:index, :show]
-  before_action :load_post, only: [:show]
+  before_action :load_user, except: :create
 
   # GET /users/:user_id/posts
   def index
-    posts = @user.posts.enabled
-    jsonapi_render json: posts, options: { count: posts.count }
+    jsonapi_render json: @user.posts, options: { count: 100 }
   end
 
   # GET /users/:user_id/posts/:id
   def show
-    jsonapi_render json: @post
+    jsonapi_render json: @user.posts.find(params[:id])
+  end
+
+  # POST /users
+  def create
+    post = Post.new(post_params)
+    if post.save
+      jsonapi_render json: post, status: :created
+    else
+      jsonapi_render_errors json: post, status: :unprocessable_entity
+    end
   end
 
   private
 
-  def load_user
-    @user = User.find(params[:user_id])
+  def post_params
+    params.require(:data).require(:attributes).permit(:title, :body)
+          .merge(user_id: author_params[:id])
   end
 
-  def load_post
-    @post = @user.posts.find(params[:id])
+  def author_params
+    params.require(:relationships).require(:author).require(:data).permit(:id)
   end
-end
-```
-
-### Errors
-
-#### Not found
-
-As you might have seen in BaseController this line will handle all errors related to not found resources:
 
-```ruby
-rescue_from ActiveRecord::RecordNotFound, with: :jsonapi_render_not_found
-```
-
-The `jsonapi_render_not_found` method will produce the following error payload:
-
-```json
-HTTP/1.1 404 Not found
-Content-Type: application/vnd.api+json
-
-{
-  "errors": [
-    {
-      "title": "Record not found",
-      "detail": "The record identified by 3 could not be found.",
-      "code": "404",
-      "status": "404"
-    }
-  ]
-}
-```
-
-In case you prefer rendering not found resources with null data and `200 OK` status code, you can use `jsonapi_render_not_found_with_null` to produce:
-
-```json
-HTTP/1.1 200 OK
-Content-Type: application/vnd.api+json
-
-{
-  "data": null
-}
+  def load_user
+    @user = User.find(params[:user_id])
+  end
+end
 ```
 
-If you need to create custom error message, check [this](https://github.com/cerebris/jsonapi-resources#error-codes).
-
 ### Initializer
 
-In order to enable a proper pagination, record count etc, let's define an initializer such as:
+In order to enable a proper pagination, record count etc, an initializer could be defined such as:
 
 ```ruby
 # config/initializers/jsonapi_resources.rb

data/lib/jsonapi/utils.rb

@@ -6,12 +6,12 @@ require 'jsonapi/utils/response'
 
 module JSONAPI
   module Utils
-    include JSONAPI::Utils::Request
-    include JSONAPI::Utils::Response
+    include Request
+    include Response
 
     def self.included(base)
       if base.respond_to?(:before_action)
-        base.before_action :setup_request, :check_request
+        base.before_action :jsonapi_request_handling
       end
     end
   end

data/lib/jsonapi/utils/request.rb

@@ -1,10 +1,15 @@
 module JSONAPI
   module Utils
     module Request
+      def jsonapi_request_handling
+        setup_request
+        check_request
+      end
+
       def setup_request
         @request ||=
           JSONAPI::Request.new(
-            params,
+            params.dup,
             context: context,
             key_formatter: key_formatter,
             server_error_callbacks: (self.class.server_error_callbacks || [])
@@ -14,6 +19,31 @@ module JSONAPI
       def check_request
         @request.errors.blank? || jsonapi_render_errors(json: @request)
       end
+
+      def resource_params
+        build_params_for(:resource)
+      end
+
+      def relationship_params
+        build_params_for(:relationship)
+      end
+
+      private
+
+      def build_params_for(param_type)
+        return {} if @request.operations.empty?
+
+        keys      = %i(attributes to_one to_many)
+        operation = @request.operations.find { |e| e.data.keys & keys == keys }
+
+        if operation.nil?
+          {}
+        elsif param_type == :relationship
+          operation.data.values_at(:to_one, :to_many).compact.reduce(&:merge)
+        else
+          operation.data[:attributes]
+        end
+      end
     end
   end
 end

data/lib/jsonapi/utils/response/formatters.rb

@@ -19,7 +19,7 @@ module JSONAPI
           JSONAPI::Utils::Support::Error.sanitize(errors).uniq
         end
 
-        protected
+        private
 
         def build_response_document(records, options)
           results = JSONAPI::OperationResults.new

data/lib/jsonapi/utils/response/support.rb

@@ -12,7 +12,7 @@ module JSONAPI
         include ::JSONAPI::Utils::Support::Pagination
         include ::JSONAPI::Utils::Support::Sort
 
-        protected
+        private
 
         def correct_media_type
           if response.body.size > 0

data/lib/jsonapi/utils/version.rb

@@ -1,5 +1,5 @@
 module JSONAPI
   module Utils
-    VERSION = '0.4.5'
+    VERSION = '0.4.6'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jsonapi-utils
 version: !ruby/object:Gem::Version
-  version: 0.4.5
+  version: 0.4.6
 platform: ruby
 authors:
 - Tiago Guedes
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-06-06 00:00:00.000000000 Z
+date: 2016-07-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jsonapi-resources