jsonapi.rb 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2625c5af20d211c8e480235ec9587d648143eda2f76ffc2a5add9bdcc5d5e1d4
+  data.tar.gz: e685d519946126bd51b3741b0980edab95d7da4f3bbb9ceca8cb248142eedd65
+SHA512:
+  metadata.gz: fe25509464222844a3511f5cb768b85e3b078939822abe88889bf8f21df91fd8460d52b81d98dadd3e74ae831b7d0c66242353007a44f631560728029d6db231
+  data.tar.gz: 789b5919fcc2b8092e9db62ddad3fc420d152b6e9a5542f2daba561a7233d5320e4a672b85bb7640bce31408a2e60788ee1b3ca65e503b766e8d3bfe0b599ee5

data/.gitignore

@@ -0,0 +1 @@
+coverage

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,22 @@
+inherit_gem:
+  rubocop-rails_config:
+    - config/rails.yml
+
+Rails:
+  Enabled: true
+
+Style/StringLiterals:
+  Enabled: true
+  EnforcedStyle: single_quotes
+
+Style/FrozenStringLiteralComment:
+  Enabled: false
+
+Metrics/LineLength:
+  Max: 80
+
+Layout/IndentationConsistency:
+  EnforcedStyle: normal
+
+Style/BlockDelimiters:
+  Enabled: true

data/.travis.yml

@@ -0,0 +1,7 @@
+---
+sudo: false
+language: ruby
+cache: bundler
+rvm:
+  - 2.5.1
+before_install: gem install bundler

data/.yardstick.yml

@@ -0,0 +1,29 @@
+---
+path: ['lib/**/*.rb']
+threshold: 100
+rules:
+  ApiTag::Presence:
+    enabled: false
+  ApiTag::Inclusion:
+    enabled: false
+  ApiTag::ProtectedMethod:
+    enabled: false
+  ApiTag::PrivateMethod:
+    enabled: false
+  ExampleTag:
+    enabled: false
+  ReturnTag:
+    enabled: true
+    exclude: []
+  Summary::Presence:
+    enabled: true
+    exclude: []
+  Summary::Length:
+    enabled: true
+    exclude: []
+  Summary::Delimiter:
+    enabled: true
+    exclude: []
+  Summary::SingleLine:
+    enabled: true
+    exclude: []

data/Gemfile

@@ -0,0 +1,6 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in jsonapi.gemspec
+gemspec
+
+gem 'jsonapi-rspec', github: 'stas/jsonapi-rspec'

data/Gemfile.lock

@@ -0,0 +1,204 @@
+GIT
+  remote: git://github.com/stas/jsonapi-rspec.git
+  revision: f223a3d5531cf2c0ce2f90aa8dac2bae46b2d499
+  specs:
+    jsonapi-rspec (0.0.2)
+      rspec-expectations
+
+PATH
+  remote: .
+  specs:
+    jsonapi.rb (1.0.0)
+      fast_jsonapi (~> 1.5)
+      ransack (~> 2.1)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    actioncable (5.2.2)
+      actionpack (= 5.2.2)
+      nio4r (~> 2.0)
+      websocket-driver (>= 0.6.1)
+    actionmailer (5.2.2)
+      actionpack (= 5.2.2)
+      actionview (= 5.2.2)
+      activejob (= 5.2.2)
+      mail (~> 2.5, >= 2.5.4)
+      rails-dom-testing (~> 2.0)
+    actionpack (5.2.2)
+      actionview (= 5.2.2)
+      activesupport (= 5.2.2)
+      rack (~> 2.0)
+      rack-test (>= 0.6.3)
+      rails-dom-testing (~> 2.0)
+      rails-html-sanitizer (~> 1.0, >= 1.0.2)
+    actionview (5.2.2)
+      activesupport (= 5.2.2)
+      builder (~> 3.1)
+      erubi (~> 1.4)
+      rails-dom-testing (~> 2.0)
+      rails-html-sanitizer (~> 1.0, >= 1.0.3)
+    activejob (5.2.2)
+      activesupport (= 5.2.2)
+      globalid (>= 0.3.6)
+    activemodel (5.2.2)
+      activesupport (= 5.2.2)
+    activerecord (5.2.2)
+      activemodel (= 5.2.2)
+      activesupport (= 5.2.2)
+      arel (>= 9.0)
+    activestorage (5.2.2)
+      actionpack (= 5.2.2)
+      activerecord (= 5.2.2)
+      marcel (~> 0.3.1)
+    activesupport (5.2.2)
+      concurrent-ruby (~> 1.0, >= 1.0.2)
+      i18n (>= 0.7, < 2)
+      minitest (~> 5.1)
+      tzinfo (~> 1.1)
+    arel (9.0.0)
+    ast (2.4.0)
+    builder (3.2.3)
+    concurrent-ruby (1.1.4)
+    crass (1.0.4)
+    diff-lcs (1.3)
+    docile (1.3.1)
+    erubi (1.8.0)
+    fast_jsonapi (1.5)
+      activesupport (>= 4.2)
+    ffaker (2.10.0)
+    globalid (0.4.2)
+      activesupport (>= 4.2.0)
+    i18n (1.5.1)
+      concurrent-ruby (~> 1.0)
+    jaro_winkler (1.5.2)
+    json (2.1.0)
+    loofah (2.2.3)
+      crass (~> 1.0.2)
+      nokogiri (>= 1.5.9)
+    mail (2.7.1)
+      mini_mime (>= 0.1.1)
+    marcel (0.3.3)
+      mimemagic (~> 0.3.2)
+    method_source (0.9.2)
+    mimemagic (0.3.3)
+    mini_mime (1.0.1)
+    mini_portile2 (2.4.0)
+    minitest (5.11.3)
+    nio4r (2.3.1)
+    nokogiri (1.10.0)
+      mini_portile2 (~> 2.4.0)
+    parallel (1.12.1)
+    parser (2.5.3.0)
+      ast (~> 2.4.0)
+    powerpack (0.1.2)
+    rack (2.0.6)
+    rack-test (1.1.0)
+      rack (>= 1.0, < 3)
+    rails (5.2.2)
+      actioncable (= 5.2.2)
+      actionmailer (= 5.2.2)
+      actionpack (= 5.2.2)
+      actionview (= 5.2.2)
+      activejob (= 5.2.2)
+      activemodel (= 5.2.2)
+      activerecord (= 5.2.2)
+      activestorage (= 5.2.2)
+      activesupport (= 5.2.2)
+      bundler (>= 1.3.0)
+      railties (= 5.2.2)
+      sprockets-rails (>= 2.0.0)
+    rails-dom-testing (2.0.3)
+      activesupport (>= 4.2.0)
+      nokogiri (>= 1.6)
+    rails-html-sanitizer (1.0.4)
+      loofah (~> 2.2, >= 2.2.2)
+    railties (5.2.2)
+      actionpack (= 5.2.2)
+      activesupport (= 5.2.2)
+      method_source
+      rake (>= 0.8.7)
+      thor (>= 0.19.0, < 2.0)
+    rainbow (3.0.0)
+    rake (12.3.2)
+    ransack (2.1.1)
+      actionpack (>= 5.0)
+      activerecord (>= 5.0)
+      activesupport (>= 5.0)
+      i18n
+    rspec (3.8.0)
+      rspec-core (~> 3.8.0)
+      rspec-expectations (~> 3.8.0)
+      rspec-mocks (~> 3.8.0)
+    rspec-core (3.8.0)
+      rspec-support (~> 3.8.0)
+    rspec-expectations (3.8.2)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.8.0)
+    rspec-mocks (3.8.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.8.0)
+    rspec-rails (3.8.1)
+      actionpack (>= 3.0)
+      activesupport (>= 3.0)
+      railties (>= 3.0)
+      rspec-core (~> 3.8.0)
+      rspec-expectations (~> 3.8.0)
+      rspec-mocks (~> 3.8.0)
+      rspec-support (~> 3.8.0)
+    rspec-support (3.8.0)
+    rubocop (0.62.0)
+      jaro_winkler (~> 1.5.1)
+      parallel (~> 1.10)
+      parser (>= 2.5, != 2.5.1.1)
+      powerpack (~> 0.1)
+      rainbow (>= 2.2.2, < 4.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (~> 1.4.0)
+    rubocop-rails_config (0.4.0)
+      railties (>= 3.0)
+      rubocop (~> 0.58)
+    ruby-progressbar (1.10.0)
+    simplecov (0.16.1)
+      docile (~> 1.1)
+      json (>= 1.8, < 3)
+      simplecov-html (~> 0.10.0)
+    simplecov-html (0.10.2)
+    sprockets (3.7.2)
+      concurrent-ruby (~> 1.0)
+      rack (> 1, < 3)
+    sprockets-rails (3.2.1)
+      actionpack (>= 4.0)
+      activesupport (>= 4.0)
+      sprockets (>= 3.0.0)
+    sqlite3 (1.3.13)
+    thor (0.20.3)
+    thread_safe (0.3.6)
+    tzinfo (1.2.5)
+      thread_safe (~> 0.1)
+    unicode-display_width (1.4.1)
+    websocket-driver (0.7.0)
+      websocket-extensions (>= 0.1.0)
+    websocket-extensions (0.1.3)
+    yard (0.9.16)
+    yardstick (0.9.9)
+      yard (~> 0.8, >= 0.8.7.2)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler
+  ffaker
+  jsonapi-rspec!
+  jsonapi.rb!
+  rails
+  rspec (~> 3.0)
+  rspec-rails
+  rubocop-rails_config
+  simplecov
+  sqlite3
+  yardstick
+
+BUNDLED WITH
+   1.16.3

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2019 Stas Suscov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,245 @@
+# JSONAPI.rb :electric_plug:
+
+So you say you need [JSON:API](https://jsonapi.org/) support in your API...
+
+> - hey how did your hackathon go?
+> - not too bad, we got Babel set up
+> - yep…
+> - yep.
+>
+>— [I Am Devloper](https://twitter.com/iamdevloper/status/787969734918668289)
+
+Here are some _codes_ to help you build your next JSON:API compliable application
+easier and faster.
+
+## But why?
+
+It's quite a hassle to setup a Ruby (Rails) web application to use and follow
+the JSON:API specifications.
+
+The idea is simple, JSONAPI.rb offers a bunch of modules/mixins/glue,
+add them to your controllers, call some methods, _profit_!
+
+Main goals:
+ * No _magic_ please
+ * No DSLs please
+ * Less code, less maintenance
+ * Good docs and test coverage
+ * Keep it up-to-date (or at least tell people this is for _grabs_)
+
+The available features include:
+
+ * object serialization powered by (Fast JSON API)
+ * [error handling](https://jsonapi.org/format/#errors) (parameters,
+   validation, generic errors)
+ * fetching of the data (support for
+   [includes](https://jsonapi.org/format/#fetching-includes) and
+   [sparse fields](https://jsonapi.org/format/#fetching-sparse-fieldsets))
+ * [filtering](https://jsonapi.org/format/#fetching-filtering) and
+   [sorting](https://jsonapi.org/format/#fetching-sorting) of the data
+   (powered by Ransack)
+ * [pagination](https://jsonapi.org/format/#fetching-pagination) support
+
+## But how?
+
+Mainly by leveraging [Fast JSON API](https://github.com/Netflix/fast_jsonapi)
+and [Ransack](https://github.com/activerecord-hackery/ransack).
+
+Thanks to everyone who worked on these amazing projects!
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'jsonapi.rb'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install jsonapi.rb
+
+## Usage
+
+To enable the support for Rails, add this to an initializer:
+
+```ruby
+# config/initializers/jsonapi.rb
+require 'jsonapi'
+
+JSONAPI::Rails.install!
+```
+
+This will register the mime type and the `jsonapi` and `jsonapi_errors`
+renderers.
+
+### Object Serialization
+
+The `jsonapi` renderer will try to guess and resolve the serializer class based
+on the object class, and if it is a collection, based on the first item in the
+collection.
+
+The naming scheme follows the `ModuleName::ClassNameSerializer` for an instance
+of the `ModuleName::ClassName`.
+
+Please follow the
+[Fast JSON API guide](https://github.com/Netflix/fast_jsonapi#serializer-definition)
+on how to define a serializer.
+
+#### Collection Meta
+
+To provide meta information for a collection, provide the `jsonapi_meta`
+controller method.
+
+Here's an example:
+
+```ruby
+class MyController < ActionController::Base
+  def index
+    render jsonapi: Model.all
+  end
+
+  private
+
+  def jsonapi_meta(resources)
+    { total: resources.count } if resources.respond_to?(:count)
+  end
+end
+```
+
+### Error handling
+
+`JSONAPI::Errors` provides a basic error handling. It will generate a valid
+error response on exceptions from strong parameters, on generic errors or
+when a record is not found.
+
+To render the validation errors, just pass it to the error renderer.
+
+Here's an example:
+
+```ruby
+class MyController < ActionController::Base
+  include JSONAPI::Errors
+
+  def update
+    raise_error! if params[:id] == 'tada'
+
+    record = Model.find(params[:id])
+
+    if record.update(params.require(:data).require(:attributes).permit!)
+      render jsonapi: record
+    else
+      render jsonapi_errors: record.errors, status: :unprocessable_entity
+    end
+  end
+end
+```
+
+### _Includes_ and sparse fields
+
+`JSONAPI::Fetching` provides support on inclusion of related resources and
+serialization of only specific fields.
+
+Here's an example:
+
+```ruby
+class MyController < ActionController::Base
+  include JSONAPI::Fetching
+
+  def index
+    render jsonapi: Model.all
+  end
+
+  private
+
+  # Overwrite/whitelist the includes
+  def jsonapi_include(resources)
+    super - [:unwanted_attribute]
+  end
+end
+```
+
+### Filtering and sorting
+
+`JSONAPI::Filtering` uses the power of
+[Ransack](https://github.com/activerecord-hackery/ransack#search-matchers)
+to filter and sort over a collection of records.
+The support is pretty extended and covers also relationships and composite
+matchers.
+
+Here's an example:
+
+```ruby
+class MyController < ActionController::Base
+  include JSONAPI::Filtering
+
+  def index
+    allowed = [:model_attr, :relationship_attr]
+
+    jsonapi_filter(Model.all, allowed) do |filtered|
+      render jsonapi: filtered.result
+    end
+  end
+end
+```
+
+This allows you to run queries like:
+
+```bash
+$ curl -X GET \
+  /api/resources?filter[model_attr_or_relationship_attr_cont_any]=value,name\
+  &sort=-model_attr,relationship_attr
+```
+
+
+### Pagination
+
+`JSONAPI::Pagination` provides support for paginating model record sets as long
+as enumerables.
+
+Here's an example:
+
+```ruby
+class MyController < ActionController::Base
+  include JSONAPI::Pagination
+
+  def index
+    jsonapi_paginate(Model.all) do |paginated|
+      render jsonapi: paginated
+    end
+  end
+end
+```
+
+This will generate the relevant pagination _links_.
+
+## Development
+
+After checking out the repo, run `bundle` to install dependencies.
+
+Then, run `rake spec` to run the tests.
+
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+To release a new version, update the version number in `version.rb`, and then
+run `bundle exec rake release`, which will create a git tag for the version,
+push git commits and tags, and push the `.gem` file to
+[rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at
+https://github.com/stas/jsonapi.rb
+
+This project is intended to be a safe, welcoming space for collaboration, and
+contributors are expected to adhere to the
+[Contributor Covenant](http://contributor-covenant.org) code of conduct.
+
+## License
+
+The gem is available as open source under the terms of the
+[MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,30 @@
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+require 'rubocop/rake_task'
+require 'yaml'
+require 'yardstick'
+
+desc('Documentation stats and measurements')
+task('qa:docs') do
+  yaml = YAML.load_file(File.expand_path('../.yardstick.yml', __FILE__))
+  config = Yardstick::Config.coerce(yaml)
+  measure = Yardstick.measure(config)
+  measure.puts
+  coverage = Yardstick.round_percentage(measure.coverage * 100)
+  exit(1) if coverage < config.threshold
+end
+
+desc('Codestyle check and linter')
+RuboCop::RakeTask.new('qa:code') do |task|
+  task.fail_on_error = true
+  task.patterns = [
+    'lib/**/*.rb',
+    'spec/**/*.rb'
+  ]
+end
+
+desc('Run CI QA tasks')
+task(qa: ['qa:docs', 'qa:code'])
+
+RSpec::Core::RakeTask.new(spec: :qa)
+task(default: :spec)

data/jsonapi.rb.gemspec

@@ -0,0 +1,37 @@
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+
+require 'jsonapi/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'jsonapi.rb'
+  spec.version       = JSONAPI::VERSION
+  spec.authors       = ['Stas Suscov']
+  spec.email         = ['stas@nerd.ro']
+
+  spec.summary       = 'So you say you need JSON:API support in your API...'
+  spec.description   = (
+    'JSON:API serialization, error handling, filtering and pagination.'
+  )
+  spec.homepage      = 'https://github.com/stas/jsonapi.rb'
+  spec.license       = 'MIT'
+
+  spec.files         = Dir.chdir(File.expand_path('..', __FILE__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(spec)/}) }
+  end
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'fast_jsonapi', '~> 1.5'
+  spec.add_dependency 'ransack', '~> 2.1'
+
+  spec.add_development_dependency 'bundler'
+  spec.add_development_dependency 'rails'
+  spec.add_development_dependency 'sqlite3'
+  spec.add_development_dependency 'ffaker'
+  spec.add_development_dependency 'rspec', '~> 3.0'
+  spec.add_development_dependency 'rspec-rails'
+  spec.add_development_dependency 'jsonapi-rspec'
+  spec.add_development_dependency 'yardstick'
+  spec.add_development_dependency 'rubocop-rails_config'
+  spec.add_development_dependency 'simplecov'
+end

data/lib/jsonapi.rb

@@ -0,0 +1,12 @@
+require 'jsonapi/errors'
+require 'jsonapi/fetching'
+require 'jsonapi/filtering'
+require 'jsonapi/pagination'
+require 'jsonapi/rails'
+require 'jsonapi/version'
+
+# JSON:API
+module JSONAPI
+  # JSONAPI media type.
+  MEDIA_TYPE = 'application/vnd.api+json'.freeze
+end

data/lib/jsonapi/active_model_error_serializer.rb

@@ -0,0 +1,42 @@
+require 'jsonapi/error_serializer'
+
+module JSONAPI
+  # [ActiveModel::Errors] serializer
+  class ActiveModelErrorSerializer < ErrorSerializer
+    set_id :object_id
+    set_type :error
+
+    attribute :status do
+      '422'
+    end
+
+    attribute :title do
+      Net::HTTP::STATUS_CODES[422]
+    end
+
+    attribute :code do |object|
+      _, error_hash = object
+      error_hash[:error]
+    end
+
+    attribute :detail do |object, params|
+      error_key, error_hash = object
+      errors_object = params[:model].errors
+      message = errors_object.generate_message(error_key, error_hash[:error])
+      errors_object.full_message(error_key, message)
+    end
+
+    attribute :source do |object, params|
+      error_key, _ = object
+      model_serializer = params[:model_serializer]
+
+      if model_serializer.attributes_to_serialize.keys.include?(error_key)
+        { pointer: "/data/attributes/#{error_key}" }
+      elsif model_serializer.relationships_to_serialize.keys.include?(error_key)
+        { pointer: "/data/relationships/#{error_key}" }
+      else
+        { pointer: '' }
+      end
+    end
+  end
+end

data/lib/jsonapi/error_serializer.rb

@@ -0,0 +1,25 @@
+require 'fast_jsonapi'
+
+module JSONAPI
+  # A simple error serializer
+  class ErrorSerializer
+    include FastJsonapi::ObjectSerializer
+
+    set_id :object_id
+    set_type :error
+
+    # Object/Hash attribute helpers.
+    [:status, :source, :title, :detail].each do |attr_name|
+      attribute attr_name do |object|
+        object.try(attr_name) || object.try(:fetch, attr_name, nil)
+      end
+    end
+
+    # Remap the root key to `errors`
+    #
+    # @return [Hash]
+    def serializable_hash
+      { errors: (super[:data] || []).map { |error| error[:attributes] } }
+    end
+  end
+end

data/lib/jsonapi/errors.rb

@@ -0,0 +1,46 @@
+require 'net/http/status'
+require 'active_support/concern'
+
+# Helpers to handle some error responses
+#
+# Most of the exceptions are handled in Rails by [ActionDispatch] middleware
+# See: https://api.rubyonrails.org/classes/ActionDispatch/ExceptionWrapper.html
+module JSONAPI::Errors
+  extend ActiveSupport::Concern
+
+  included do
+    rescue_from StandardError do |exception|
+      error = { status: '500', title: Net::HTTP::STATUS_CODES[500] }
+      render jsonapi_errors: [error], status: :internal_server_error
+    end
+
+    [
+      ActiveRecord::RecordNotFound
+    ].each do |exception_class|
+      rescue_from exception_class do |exception|
+        error = { status: '404', title: Net::HTTP::STATUS_CODES[404] }
+        render jsonapi_errors: [error], status: :not_found
+      end
+    end
+
+    [
+      ActionController::ParameterMissing
+    ].each do |exception_class|
+      rescue_from exception_class do |exception|
+        source = { pointer: '' }
+
+        if !%w{data attributes relationships}.include?(exception.param.to_s)
+          source[:pointer] = "/data/attributes/#{exception.param}"
+        end
+
+        error = {
+          status: '422',
+          title: Net::HTTP::STATUS_CODES[422],
+          source: source
+        }
+
+        render jsonapi_errors: [error], status: :unprocessable_entity
+      end
+    end
+  end
+end

data/lib/jsonapi/fetching.rb

@@ -0,0 +1,26 @@
+# Inclusion and sparse fields support
+module JSONAPI::Fetching
+  private
+
+  # Extracts and formats sparse fieldsets
+  #
+  # Ex.: `GET /resource?fields[relationship]=id,created_at`
+  #
+  # @return [Hash]
+  def jsonapi_fields
+    ActiveSupport::HashWithIndifferentAccess.new.tap do |h|
+      (params[:fields] || []).each do |k, v|
+        h[k] = v.split(',').map(&:strip).compact
+      end
+    end
+  end
+
+  # Extracts and whitelists allowed includes
+  #
+  # Ex.: `GET /resource?include=relationship,relationship.subrelationship`
+  #
+  # @return [Array]
+  def jsonapi_include
+    params['include'].to_s.split(',').map(&:strip).compact
+  end
+end

data/lib/jsonapi/filtering.rb

@@ -0,0 +1,73 @@
+require 'ransack/predicate'
+
+# Filtering and sorting support
+module JSONAPI::Filtering
+  private
+
+  # Applies filtering and sorting to a set of resources if requested
+  #
+  # The fields follow [Ransack] specifications.
+  # See: https://github.com/activerecord-hackery/ransack#search-matchers
+  #
+  # Ex.: `GET /resource?filter[region_matches_any]=Lisb%&sort=-created_at,id`
+  #
+  # @param allowed_fields [Array] a list of allowed fields to be filtered
+  # @return [ActiveRecord::Base] a collection of resources
+  def jsonapi_filter(resources, allowed_fields)
+    extracted_params = jsonapi_filter_params(allowed_fields)
+    extracted_params[:sorts] = jsonapi_sort_params(allowed_fields)
+    resources = resources.ransack(extracted_params)
+    block_given? ? yield(resources) : resources
+  end
+
+  # Extracts and whitelists allowed fields to be filtered
+  #
+  # The fields follow [Ransack] specifications.
+  # See: https://github.com/activerecord-hackery/ransack#search-matchers
+  #
+  # @param allowed_fields [Array] a list of allowed fields to be filtered
+  # @return [Hash] to be passed to [ActiveRecord::Base#order]
+  def jsonapi_filter_params(allowed_fields)
+    filtered = {}
+    requested = params[:filter] || {}
+    allowed_fields = allowed_fields.map(&:to_s)
+
+    requested.each_pair do |requested_field, to_filter|
+      field_name = requested_field.dup
+      predicate = Ransack::Predicate.detect_and_strip_from_string!(field_name)
+      predicate = Ransack::Predicate.named(predicate)
+
+      field_names = field_name.split(/_and_|_or_/)
+
+      if to_filter.is_a?(String) && to_filter.include?(',')
+        to_filter = to_filter.split(',')
+      end
+
+      if predicate && (field_names - allowed_fields).empty?
+        filtered[requested_field] = to_filter
+      end
+    end
+
+    filtered
+  end
+
+  # Extracts and whitelists allowed fields to be sorted
+  #
+  # @param allowed_fields [Array] a list of allowed fields to be sorted
+  # @return [Hash] to be passed to [ActiveRecord::Base#order]
+  def jsonapi_sort_params(allowed_fields)
+    requested = params[:sort].to_s.split(',')
+    requested.map! do |requested_field|
+      desc = requested_field.to_s.start_with?('-')
+      [
+        desc ? requested_field[1..-1] : requested_field,
+        desc ? 'desc' : 'asc'
+      ]
+    end
+
+    # Convert to strings instead of hashes to allow joined table columns.
+    requested.to_h.slice(*allowed_fields.map(&:to_s)).map do |field, dir|
+      [field, dir].join(' ')
+    end
+  end
+end

data/lib/jsonapi/pagination.rb

@@ -0,0 +1,80 @@
+# Pagination support
+module JSONAPI::Pagination
+  private
+
+  # Default number of items per page.
+  JSONAPI_PAGE_SIZE = 30
+
+  # Applies pagination to a set of resources
+  #
+  # Ex.: `GET /resource?page[number]=2&page[size]=10`
+  #
+  # @return [ActiveRecord::Base] a collection of resources
+  def jsonapi_paginate(resources)
+    offset, limit, _ = jsonapi_pagination_params
+
+    if resources.respond_to?(:offset)
+      resources = resources.offset(offset).limit(limit)
+    else
+      resources = resources[(offset)..(offset + limit)]
+    end
+
+    block_given? ? yield(resources) : resources
+  end
+
+  # Generates the pagination links
+  #
+  # @return [Array]
+  def jsonapi_pagination(resources)
+    links = {
+      self: request.base_url + request.original_fullpath
+    }
+
+    return links unless resources.respond_to?(:many?)
+
+    _, limit, page = jsonapi_pagination_params
+
+    original_params = params.except(
+      *request.path_parameters.keys.map(&:to_s)).to_unsafe_h
+    original_params[:page] ||= {}
+    original_url = request.base_url + request.path + '?'
+
+    if resources.respond_to?(:unscope)
+      total = resources.unscope(:limit, :offset).count()
+    else
+      total = resources.size
+    end
+
+    last_page = [1, (total.to_f / limit).ceil].max
+
+    if page > 1
+      original_params[:page][:number] = 1
+      links[:first] = original_url + CGI.unescape(original_params.to_query)
+      original_params[:page][:number] = page - 1
+      links[:prev] = original_url + CGI.unescape(original_params.to_query)
+    end
+
+    if page < last_page
+      original_params[:page][:number] = page + 1
+      links[:next] = original_url + CGI.unescape(original_params.to_query)
+      original_params[:page][:number] = last_page
+      links[:last] = original_url + CGI.unescape(original_params.to_query)
+    end
+
+    links
+  end
+
+  # Extracts the pagination params
+  #
+  # @return [Array] with the offset, limit and the current page number
+  def jsonapi_pagination_params
+    def_per_page = self.class.const_get(:JSONAPI_PAGE_SIZE).to_i
+
+    pagination = params[:page].try(:slice, :number, :size) || {}
+    per_page = (pagination[:size] || def_per_page).to_f.to_i
+    per_page = def_per_page if per_page > def_per_page
+    num = [1, pagination[:number].to_f.to_i].max
+
+    [(num - 1) * per_page, per_page, num]
+  end
+end

data/lib/jsonapi/rails.rb

@@ -0,0 +1,98 @@
+require 'jsonapi/error_serializer'
+require 'jsonapi/active_model_error_serializer'
+
+# Rails integration
+module JSONAPI::Rails
+  # Updates the mime types and registers the renderers
+  #
+  # @return [NilClass]
+  def self.install!
+    return unless defined?(::Rails)
+
+    Mime::Type.register JSONAPI::MEDIA_TYPE, :jsonapi
+
+    # Map the JSON parser to the JSONAPI mime type requests.
+    if Rails::VERSION::MAJOR >= 5
+      parser = ActionDispatch::Request.parameter_parsers[:json]
+      ActionDispatch::Request.parameter_parsers[:jsonapi] = parser
+    else
+      parser = ActionDispatch::ParamsParser::DEFAULT_PARSERS[Mime[:json]]
+      ActionDispatch::ParamsParser::DEFAULT_PARSERS[Mime[:jsonapi]] = parser
+    end
+
+    self.add_renderer!
+    self.add_errors_renderer!
+  end
+
+  # Adds the error renderer
+  #
+  # @return [NilClass]
+  def self.add_errors_renderer!
+    ActionController::Renderers.add(:jsonapi_errors) do |resource, options|
+      self.content_type ||= Mime[:jsonapi]
+
+      resource = [resource] unless JSONAPI::Rails.is_collection?(resource)
+
+      return JSONAPI::ErrorSerializer.new(resource, options)
+        .serialized_json unless resource.is_a?(ActiveModel::Errors)
+
+      errors = []
+      model = resource.marshal_dump.first
+      model_serializer = JSONAPI::Rails.serializer_class(model)
+
+      resource.details.each do |error_key, error_hashes|
+        error_hashes.each do |error_hash|
+          errors << [ error_key, error_hash ]
+        end
+      end
+
+      JSONAPI::ActiveModelErrorSerializer.new(
+        errors, params: { model: model, model_serializer: model_serializer }
+      ).serialized_json
+    end
+  end
+
+  # Adds the default renderer
+  #
+  # @return [NilClass]
+  def self.add_renderer!
+    ActionController::Renderers.add(:jsonapi) do |resource, options|
+      self.content_type ||= Mime[:jsonapi]
+
+      options[:meta] ||= (
+        jsonapi_meta(resource) if respond_to?(:jsonapi_meta, true))
+      options[:links] ||= (
+        jsonapi_pagination(resource) if respond_to?(:jsonapi_pagination, true))
+
+      # If it's an empty collection, return it directly.
+      if JSONAPI::Rails.is_collection?(resource) && !resource.any?
+        return options.slice(:meta, :links).merge(data: []).to_json
+      end
+
+      options[:fields] ||= jsonapi_fields if respond_to?(:jsonapi_fields, true)
+      options[:include] ||= (
+        jsonapi_include if respond_to?(:jsonapi_include, true))
+
+      serializer_class = JSONAPI::Rails.serializer_class(resource)
+      serializer_class.new(resource, options).serialized_json
+    end
+  end
+
+  # Checks if an object is a collection
+  #
+  # @param object [Object] to check
+  # @return [TrueClass] upon success
+  def self.is_collection?(object)
+    object.is_a?(Enumerable) && !object.respond_to?(:each_pair)
+  end
+
+  # Resolves resource serializer class
+  #
+  # @return [Class]
+  def self.serializer_class(resource)
+    klass = resource.class
+    klass = resource.first.class if self.is_collection?(resource)
+
+    "#{klass.name}Serializer".constantize
+  end
+end

data/lib/jsonapi/version.rb

@@ -0,0 +1,3 @@
+module JSONAPI
+  VERSION = '1.0.0'
+end

metadata

@@ -0,0 +1,231 @@
+--- !ruby/object:Gem::Specification
+name: jsonapi.rb
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Stas Suscov
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2019-01-13 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: fast_jsonapi
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+- !ruby/object:Gem::Dependency
+  name: ransack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: ffaker
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rspec-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: jsonapi-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: yardstick
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rails_config
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: JSON:API serialization, error handling, filtering and pagination.
+email:
+- stas@nerd.ro
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".rubocop.yml"
+- ".travis.yml"
+- ".yardstick.yml"
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.md
+- Rakefile
+- jsonapi.rb.gemspec
+- lib/jsonapi.rb
+- lib/jsonapi/active_model_error_serializer.rb
+- lib/jsonapi/error_serializer.rb
+- lib/jsonapi/errors.rb
+- lib/jsonapi/fetching.rb
+- lib/jsonapi/filtering.rb
+- lib/jsonapi/pagination.rb
+- lib/jsonapi/rails.rb
+- lib/jsonapi/version.rb
+homepage: https://github.com/stas/jsonapi.rb
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.1
+signing_key: 
+specification_version: 4
+summary: So you say you need JSON:API support in your API...
+test_files: []