jsonapi-utils 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: fbc9435ea77e7a938e5c3cd34b701e48509294aa
-  data.tar.gz: af2c51ee9c5bb6f5baffa1aa8bec5706befd546f
+  metadata.gz: 7dd1257dc06616941f1a935884e1b3e18ced4898
+  data.tar.gz: e464f7c33b4c462e6a9ddc94d669f0b1558a6b6e
 SHA512:
-  metadata.gz: f60cd55bdc532063292bdddb6fca175f25d9b82d8fc3d1359481f053499b13eae60174884fd77847131ec3996f5f7ec4e9ca50f5f20c04d51cd0dc036de9aaed
-  data.tar.gz: c37add6ab91aa7a08c2c49131eea9ce478f403250a43cafaed81d3d39273de1db5bf330aadafe5028a502c07e78eeef84cf417583bc7fb7d83b6db2d050b99b3
+  metadata.gz: 231eff83798cb798e4c3e3e28821acea750b82b9b0c51a479678bc9523d7ff815bb8e1151272ace7a7da9abb445751e49450fc0b7f0386efa00f97f98090b56c
+  data.tar.gz: 7a5a0d73d18304b431e61788769cf603411c01da961de76865d1499b1f6e4974934ba5eb7fe0e0e397b2dc17e0175b4f55cb72a3cefe31f36f13a0e1b621a021

data/README.md

@@ -1,36 +1,576 @@
 # JSONAPI::Utils
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/jsonapi-utils`. To experiment with that code, run `bin/console` for an interactive prompt.
-
-Required doc:
-
-* Describe something about the awesome `jsonapi-resources` gem
-* Describe how it's easy to serialize JSON API-based responses using the `jsonapi-utils` gem
-* JSONAPI::Utils#jsonapi_render (show options like `json`, `resource`, `model`, `scope` and `count`)
-* JSONAPI::Utils#jsonapi_serialize
-* Example of a model
-* Example of a resource
-* Example of a base controller and another whatever controller
+JSON::Utils is a simple way to get a full-featured [JSON API](jsonapi.org) serialization in your
+controller's responses. This gem works on top of the awesome gem [jsonapi-resources](https://github.com/cerebris/jsonapi-resources),
+bringing to controllers a Rails-native way to render data.
 
 ## Installation
 
-Add this line to your application's Gemfile:
+Add these lines to your application's Gemfile:
 
 ```ruby
+gem 'jsonapi-resources', '~> 0.5.7'
 gem 'jsonapi-utils'
 ```
 
 And then execute:
 
-    $ bundle
+```shell
+$ bundle
+```
+
+## Macros
+
+* `jsonapi_render`: it works like ActionController's `render` method, receiving model objects and
+rendering them into JSON API's data format.
+
+* `jsonapi_serialize`: in the backstage, it's the method that actually parsers model objects or hashes and builds JSON data.
+It can be called anywhere in controllers, concerns etc.
+
+## Options
+
+Those macros accept the following options:
+
+* `resource`: explicitly points the resource to be used in the serialization. By default, JSONAPI::Utils will
+select resources by inferencing from controller's name.
 
-Or install it yourself as:
+```ruby
+# If in UsersController for some reason it needs to render a different resource:
+jsonapi_render json: Post.all, options: { resource: PostResource }
+```
+
+* `count`: explicitly points the total count of records for the request, in order to build a proper pagination. By default, JSONAPI::Utils will
+count the total number of records for a given resource.
 
-    $ gem install jsonapi-utils
+```ruby
+users = User.all
+jsonapi_render json: users, options: { count: users.size }
+```
 
 ## Usage
 
-TODO: Write usage instructions here
+Let's say we have a Rails app for a super simple blog.
+
+### Models
+
+```ruby
+# app/models/user.rb
+class User < ActiveRecord::Base
+  has_many :posts
+  validates :first_name, :last_name, presence: true
+end
+
+# app/models/user.rb
+class Post < ActiveRecord::Base
+  belongs_to :author, class_name: 'User', foreign_key: 'user_id'
+  validates :title, :body, presence: true
+end
+```
+
+### Resources
+
+Here is where we define how the serialization will behave:
+
+```ruby
+# app/resources/user_resource.rb
+class UserResource < JSONAPI::Resource
+  attributes :first_name, :last_name, :full_name, :birthday
+  attribute :full_name
+
+  has_many :posts
+
+  def full_name
+    "#{@model.first_name} #{@model.last_name}"
+  end
+end
+
+# app/resources/post_resource.rb
+class PostResource < JSONAPI::Resource
+  attributes :title, :body
+  has_one :author
+end
+```
+
+### Routes & Controllers
+
+Let's define our routes using the `jsonapi_resources` and `jsonapi_links` macros provied by the `jsonapi-resources` gem:
+
+```ruby
+Rails.application.routes.draw do
+  jsonapi_resources :users do
+    jsonapi_resources :posts
+    jsonapi_links :posts
+  end
+end
+```
+
+And a base controller to include the features from `jsonapi-resources` and `jsonapi-utils`:
+
+```ruby
+# app/controllers/base_controller.rb
+class BaseController < JSONAPI::ResourceController
+  include JSONAPI::Utils
+  protect_from_forgery with: :null_session
+  rescue_from ActiveRecord::RecordNotFound, with: :jsonapi_render_not_found
+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.
+
+```ruby
+# app/controllers/users_controller.rb
+class UsersController < BaseController
+  before_action :load_user, only: [:show]
+
+  # GET /users
+  def index
+    users = User.all
+    jsonapi_render json: users, options: { count: users.size }
+  end
+
+  # GET /users/:id
+  def show
+    jsonapi_render json: @user
+  end
+
+  private
+
+  def load_user
+    @user = User.find(params[:id])
+  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]
+
+  # GET /users/:user_id/posts
+  def index
+    jsonapi_render json: @user.posts, options: { count: @user.posts.size }
+  end
+
+  # GET /users/:user_id/posts/:id
+  def show
+    jsonapi_render json: @post
+  end
+
+  private
+
+  def load_user
+    @user = User.find(params[:user_id])
+  end
+
+  def load_post
+    @post = @user.posts.find(params[:id])
+  end
+end
+```
+
+### Erros
+
+#### 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.",
+      "id": null,
+      "href": null,
+      "code": 404,
+      "source": null,
+      "links": null,
+      "status": "not_found"
+    }
+  ]
+}
+```
+
+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
+}
+```
+
+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:
+
+```ruby
+# config/initializers/jsonapi_resources.rb
+JSONAPI.configure do |config|
+  config.json_key_format = :underscored_key
+  config.route_format = :dasherized_route
+
+  config.operations_processor = :active_record
+
+  config.allow_include = true
+  config.allow_sort = true
+  config.allow_filter = true
+
+  config.raise_if_parameters_not_allowed = true
+
+  config.default_paginator = :paged
+
+  config.top_level_links_include_pagination = true
+
+  config.default_page_size = 10
+  config.maximum_page_size = 20
+
+  config.top_level_meta_include_record_count = true
+  config.top_level_meta_record_count_key = :record_count
+
+  config.use_text_errors = false
+
+  config.exception_class_whitelist = []
+
+  config.always_include_to_one_linkage_data = false
+end
+```
+
+You may want a different configuration for your API. For more information check [this](https://github.com/cerebris/jsonapi-resources/#configuration).
+
+### Requests & Responses
+
+Here's some examples of requests – based on those sample [controllers](#routes--controllers) – and their respective JSON responses.
+
+* [Collection](#collection)
+* [Collection (options)](#collection-options)
+* [Single record](#single-record)
+* [Record (options)](#single-record-options)
+* [Relationships (identifier objects)](#relationships-identifier-objects)
+* [Nested resources](#nested-resources)
+
+#### Collection
+
+Request:
+
+```
+GET /users HTTP/1.1
+Accept: application/vnd.api+json
+```
+
+Response:
+
+```json
+HTTP/1.1 200 OK
+Content-Type: application/vnd.api+json
+
+{
+  "data": [
+    {
+      "id": "1",
+      "type": "users",
+      "links": {
+        "self": "http://api.myblog.com/users/1"
+      },
+      "attributes": {
+        "first_name": "Tiago",
+        "last_name": "Guedes",
+        "full_name": "Tiago Guedes",
+        "birthday": null
+      },
+      "relationships": {
+        "posts": {
+          "links": {
+            "self": "http://api.myblog.com/users/1/relationships/posts",
+            "related": "http://api.myblog.com/users/1/posts"
+          }
+        }
+      }
+    },
+    {
+      "id": "2",
+      "type": "users",
+      "links": {
+        "self": "http://api.myblog.com/users/2"
+      },
+      "attributes": {
+        "first_name": "Douglas",
+        "last_name": "André",
+        "full_name": "Douglas André",
+        "birthday": null
+      },
+      "relationships": {
+        "posts": {
+          "links": {
+            "self": "http://api.myblog.com/users/2/relationships/posts",
+            "related": "http://api.myblog.com/users/2/posts"
+          }
+        }
+      }
+    }
+  ],
+  "meta": {
+    "record_count": 2
+  },
+  "links": {
+    "first": "http://api.myblog.com/users?page%5Bnumber%5D=1&page%5Bsize%5D=10",
+    "last": "http://api.myblog.com/users?page%5Bnumber%5D=1&page%5Bsize%5D=10"
+  }
+}
+```
+
+#### Collection (options)
+
+Request:
+
+```
+GET /users?include=posts&fields[users]=full_name,posts&fields[posts]=title&page[number]=1&page[size]=1 HTTP/1.1
+Accept: application/vnd.api+json
+```
+
+Response:
+
+```json
+HTTP/1.1 200 OK
+Content-Type: application/vnd.api+json
+
+{
+  "data": [
+    {
+      "id": "1",
+      "type": "users",
+      "links": {
+        "self": "http://api.myblog.com/users/1"
+      },
+      "attributes": {
+        "full_name": "Tiago Guedes"
+      },
+      "relationships": {
+        "posts": {
+          "links": {
+            "self": "http://api.myblog.com/users/1/relationships/posts",
+            "related": "http://api.myblog.com/users/1/posts"
+          },
+          "data": [
+            {
+              "type": "posts",
+              "id": "1"
+            }
+          ]
+        }
+      }
+    }
+  ],
+  "included": [
+    {
+      "id": "1",
+      "type": "posts",
+      "links": {
+        "self": "http://api.myblog.com/posts/1"
+      },
+      "attributes": {
+        "title": "An awesome post"
+      }
+    }
+  ],
+  "meta": {
+    "record_count": 2
+  },
+  "links": {
+    "first": "http://api.myblog.com/users?fields%5Bposts%5D=title&fields%5Busers%5D=full_name%2Cposts&include=posts&page%5Bnumber%5D=1&page%5Bsize%5D=1",
+    "next": "http://api.myblog.com/users?fields%5Bposts%5D=title&fields%5Busers%5D=full_name%2Cposts&include=posts&page%5Bnumber%5D=2&page%5Bsize%5D=1",
+    "last": "http://api.myblog.com/users?fields%5Bposts%5D=title&fields%5Busers%5D=full_name%2Cposts&include=posts&page%5Bnumber%5D=2&page%5Bsize%5D=1"
+  }
+}
+```
+
+#### Single record
+
+Request:
+
+```
+GET /users/1 HTTP/1.1
+Accept: application/vnd.api+json
+```
+
+Response:
+
+```json
+HTTP/1.1 200 OK
+Content-Type: application/vnd.api+json
+
+{
+  "data": {
+    "id": "1",
+    "type": "users",
+    "links": {
+      "self": "http://api.myblog.com/users/1"
+    },
+    "attributes": {
+      "first_name": "Tiago",
+      "last_name": "Guedes",
+      "full_name": "Tiago Guedes",
+      "birthday": null
+    },
+    "relationships": {
+      "posts": {
+        "links": {
+          "self": "http://api.myblog.com/users/1/relationships/posts",
+          "related": "http://api.myblog.com/users/1/posts"
+        }
+      }
+    }
+  }
+}
+```
+
+#### Single record (options)
+
+Request:
+
+```
+GET /users/1?include=posts&fields[users]=full_name,posts&fields[posts]=title HTTP/1.1
+Accept: application/vnd.api+json
+```
+
+Response:
+
+```json
+HTTP/1.1 200 OK
+Content-Type: application/vnd.api+json
+
+{
+  "data": {
+    "id": "1",
+    "type": "users",
+    "links": {
+      "self": "http://api.myblog.com/users/1"
+    },
+    "attributes": {
+      "full_name": "Tiago Guedes"
+    },
+    "relationships": {
+      "posts": {
+        "links": {
+          "self": "http://api.myblog.com/users/1/relationships/posts",
+          "related": "http://api.myblog.com/users/1/posts"
+        },
+        "data": [
+          {
+            "type": "posts",
+            "id": "1"
+          }
+        ]
+      }
+    }
+  },
+  "included": [
+    {
+      "id": "1",
+      "type": "posts",
+      "links": {
+        "self": "http://api.myblog.com/posts/1"
+      },
+      "attributes": {
+        "title": "An awesome post"
+      }
+    }
+  ]
+}
+```
+
+#### Relationships (identifier objects)
+
+Request:
+
+```
+GET /users/1/relationships/posts HTTP/1.1
+Accept: application/vnd.api+json
+```
+
+Response:
+
+```json
+HTTP/1.1 200 OK
+Content-Type: application/vnd.api+json
+
+{
+  "links": {
+    "self": "http://api.myblog.com/users/1/relationships/posts",
+    "related": "http://api.myblog.com/users/1/posts"
+  },
+  "data": [
+    {
+      "type": "posts",
+      "id": "1"
+    }
+  ]
+}
+```
+
+#### Nested resources
+
+Request:
+
+```
+GET /users/1/posts HTTP/1.1
+Accept: application/vnd.api+json
+```
+
+Response:
+
+```json
+HTTP/1.1 200 OK
+Content-Type: application/vnd.api+json
+
+{
+  "data": [
+    {
+      "id": "1",
+      "type": "posts",
+      "links": {
+        "self": "http://api.myblog.com/posts/1"
+      },
+      "attributes": {
+        "title": "An awesome post",
+        "body": "Lorem ipsum dolot sit amet"
+      },
+      "relationships": {
+        "author": {
+          "links": {
+            "self": "http://api.myblog.com/posts/1/relationships/author",
+            "related": "http://api.myblog.com/posts/1/author"
+          }
+        }
+      }
+    }
+  ],
+  "meta": {
+    "record_count": 1
+  },
+  "links": {
+    "first": "http://api.myblog.com/posts?page%5Bnumber%5D=1&page%5Bsize%5D=10",
+    "last": "http://api.myblog.com/posts?page%5Bnumber%5D=1&page%5Bsize%5D=10"
+  }
+}
+```
 
 ## Development
 

data/jsonapi-utils.gemspec

@@ -9,8 +9,8 @@ Gem::Specification.new do |spec|
   spec.authors       = ["Tiago Guedes", "Douglas André"]
   spec.email         = ["tiagopog@gmail.com", "douglas@beautydate.com.br"]
 
-  spec.summary       = %q{Full-featured JSON API serialization in a simple way}
-  spec.description   = %q{A Rails-way to get your API's data serialized following the JSON API's specs (http://jsosapi.org)}
+  spec.summary       = %q{JSON::Utils is a simple way to get a full-featured JSON API serialization for your controller's responses.}
+  spec.description   = %q{A Rails way to get your API's data following the JSON API's specs (http://jsosapi.org)}
   spec.homepage      = "https://github.com/b2beauty/jsonapi-utils"
   spec.license       = "MIT"
 

data/lib/jsonapi/utils.rb

@@ -1,4 +1,4 @@
-require "jsonapi/utils/version"
+require 'jsonapi/utils/version'
 
 module JSONAPI
   module Utils

data/lib/jsonapi/utils/version.rb

@@ -1,5 +1,5 @@
 module JSONAPI
   module Utils
-    VERSION = "0.2.0"
+    VERSION = '0.2.1'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jsonapi-utils
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Tiago Guedes
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2015-09-14 00:00:00.000000000 Z
+date: 2015-09-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -53,8 +53,7 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: A Rails-way to get your API's data serialized following the JSON API's
-  specs (http://jsosapi.org)
+description: A Rails way to get your API's data following the JSON API's specs (http://jsosapi.org)
 email:
 - tiagopog@gmail.com
 - douglas@beautydate.com.br
@@ -95,8 +94,9 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.8
+rubygems_version: 2.4.5.1
 signing_key: 
 specification_version: 4
-summary: Full-featured JSON API serialization in a simple way
+summary: JSON::Utils is a simple way to get a full-featured JSON API serialization
+  for your controller's responses.
 test_files: []