infinum_json_api_setup 0.0.3

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 59daa791c91a766c904582a3ca9399c6a18cb8c98dedbd77e00e4ac6a09eabd8
+  data.tar.gz: 353a09469052bb6177dc8105120f3bb45e4da7056f59f4f6a89a78349da1da72
+SHA512:
+  metadata.gz: 524c5e641919c2bd20628750731bc469d739bfa6ebc2847ae7cf6300d7d7ab38ed5f514bca70e643da513e3c4fa7c3ca55aa62adf19db7c581f3a147bb96d5b7
+  data.tar.gz: 10b48c0f0322478d378dab1e0adbcdc97eed949067cd4c38d34bbdc743cfc421eb480fae6d7ff2510869cfeb8c8e575cbf47fd764ac12481ce1c8e6b74541b4b

data/.gitignore

@@ -0,0 +1,6 @@
+/spec/examples.txt
+/spec/dummy/log/*.log
+/test/dummy/storage/
+/spec/dummy/tmp/
+
+coverage

data/.overcommit.yml

@@ -0,0 +1,26 @@
+gemfile: Gemfile
+
+CommitMsg:
+  HardTabs:
+    enabled: true
+
+PreCommit:
+  BundleAudit:
+    enabled: true
+    flags: ['--update']
+    on_warn: fail
+    command: ['bundle', 'exec', 'bundle-audit']
+
+  BundleCheck:
+    enabled: true
+
+  RuboCop:
+    enabled: true
+    on_warn: fail
+    command: ['bundle', 'exec', 'rubocop']
+
+  TrailingWhitespace:
+    enabled: true
+
+  HardTabs:
+    enabled: true

data/.rspec

@@ -0,0 +1,2 @@
+--require rails_helper
+--color

data/.rubocop.yml

@@ -0,0 +1,29 @@
+inherit_gem:
+  rubocop-infinum: rubocop.yml
+
+require:
+  - rubocop-infinum
+  - rubocop-rake
+
+Metrics/BlockLength:
+  Exclude:
+    - 'spec/**/*_spec.rb'
+
+RSpec/ExampleLength:
+  Max: 10
+
+RSpec/MultipleExpectations:
+  Max: 5
+
+Style/AccessorGrouping:
+  EnforcedStyle: separated
+
+Style/FrozenStringLiteralComment:
+  Enabled: false
+
+AllCops:
+  TargetRubyVersion: 2.7
+  Exclude:
+    - 'spec/dummy/db/schema.rb'
+    - 'spec/dummy/db/migrate/*.rb'
+  NewCops: enable

data/.ruby-version

@@ -0,0 +1 @@
+2.7.2

data/.simplecov

@@ -0,0 +1,3 @@
+SimpleCov.start do
+  add_filter %r{/spec/dummy}
+end

data/Gemfile

@@ -0,0 +1,10 @@
+source 'https://rubygems.org'
+
+gem 'bundler-audit', require: false
+gem 'factory_bot', '~> 6.2'
+gem 'faker', '~> 2.18'
+gem 'rubocop', '~> 1.0', require: false
+gem 'rubocop-infinum', require: false
+gem 'rubocop-rake', require: false
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,268 @@
+PATH
+  remote: .
+  specs:
+    infinum_json_api_setup (0.0.3)
+      json_schemer (~> 0.2)
+      jsonapi_parameters
+      pagy
+      rails
+      responders
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    actioncable (6.1.4.1)
+      actionpack (= 6.1.4.1)
+      activesupport (= 6.1.4.1)
+      nio4r (~> 2.0)
+      websocket-driver (>= 0.6.1)
+    actionmailbox (6.1.4.1)
+      actionpack (= 6.1.4.1)
+      activejob (= 6.1.4.1)
+      activerecord (= 6.1.4.1)
+      activestorage (= 6.1.4.1)
+      activesupport (= 6.1.4.1)
+      mail (>= 2.7.1)
+    actionmailer (6.1.4.1)
+      actionpack (= 6.1.4.1)
+      actionview (= 6.1.4.1)
+      activejob (= 6.1.4.1)
+      activesupport (= 6.1.4.1)
+      mail (~> 2.5, >= 2.5.4)
+      rails-dom-testing (~> 2.0)
+    actionpack (6.1.4.1)
+      actionview (= 6.1.4.1)
+      activesupport (= 6.1.4.1)
+      rack (~> 2.0, >= 2.0.9)
+      rack-test (>= 0.6.3)
+      rails-dom-testing (~> 2.0)
+      rails-html-sanitizer (~> 1.0, >= 1.2.0)
+    actiontext (6.1.4.1)
+      actionpack (= 6.1.4.1)
+      activerecord (= 6.1.4.1)
+      activestorage (= 6.1.4.1)
+      activesupport (= 6.1.4.1)
+      nokogiri (>= 1.8.5)
+    actionview (6.1.4.1)
+      activesupport (= 6.1.4.1)
+      builder (~> 3.1)
+      erubi (~> 1.4)
+      rails-dom-testing (~> 2.0)
+      rails-html-sanitizer (~> 1.1, >= 1.2.0)
+    activejob (6.1.4.1)
+      activesupport (= 6.1.4.1)
+      globalid (>= 0.3.6)
+    activemodel (6.1.4.1)
+      activesupport (= 6.1.4.1)
+    activerecord (6.1.4.1)
+      activemodel (= 6.1.4.1)
+      activesupport (= 6.1.4.1)
+    activestorage (6.1.4.1)
+      actionpack (= 6.1.4.1)
+      activejob (= 6.1.4.1)
+      activerecord (= 6.1.4.1)
+      activesupport (= 6.1.4.1)
+      marcel (~> 1.0.0)
+      mini_mime (>= 1.1.0)
+    activesupport (6.1.4.1)
+      concurrent-ruby (~> 1.0, >= 1.0.2)
+      i18n (>= 1.6, < 2)
+      minitest (>= 5.1)
+      tzinfo (~> 2.0)
+      zeitwerk (~> 2.3)
+    ast (2.4.2)
+    builder (3.2.4)
+    bundler-audit (0.8.0)
+      bundler (>= 1.2.0, < 3)
+      thor (~> 1.0)
+    childprocess (4.1.0)
+    coderay (1.1.3)
+    concurrent-ruby (1.1.9)
+    crass (1.0.6)
+    diff-lcs (1.4.4)
+    docile (1.4.0)
+    ecma-re-validator (0.3.0)
+      regexp_parser (~> 2.0)
+    erubi (1.10.0)
+    factory_bot (6.2.0)
+      activesupport (>= 5.0.0)
+    faker (2.18.0)
+      i18n (>= 1.6, < 2)
+    globalid (0.5.2)
+      activesupport (>= 5.0)
+    hana (1.3.7)
+    i18n (1.8.10)
+      concurrent-ruby (~> 1.0)
+    iniparse (1.5.0)
+    json_schemer (0.2.18)
+      ecma-re-validator (~> 0.3)
+      hana (~> 1.3)
+      regexp_parser (~> 2.0)
+      uri_template (~> 0.7)
+    jsonapi-query_builder (0.1.9)
+      activerecord (>= 5)
+      pagy (~> 3.5)
+    jsonapi-serializer (2.2.0)
+      activesupport (>= 4.2)
+    jsonapi_parameters (2.3.0)
+      actionpack (>= 4.1.8)
+      activesupport (>= 4.1.8)
+    loofah (2.12.0)
+      crass (~> 1.0.2)
+      nokogiri (>= 1.5.9)
+    mail (2.7.1)
+      mini_mime (>= 0.1.1)
+    marcel (1.0.1)
+    method_source (1.0.0)
+    mini_mime (1.1.1)
+    mini_portile2 (2.6.1)
+    minitest (5.14.4)
+    nio4r (2.5.8)
+    nokogiri (1.12.4)
+      mini_portile2 (~> 2.6.1)
+      racc (~> 1.4)
+    overcommit (0.58.0)
+      childprocess (>= 0.6.3, < 5)
+      iniparse (~> 1.4)
+      rexml (~> 3.2)
+    pagy (3.13.0)
+    parallel (1.20.1)
+    parser (3.0.2.0)
+      ast (~> 2.4.1)
+    pg (1.2.3)
+    pry (0.14.1)
+      coderay (~> 1.1)
+      method_source (~> 1.0)
+    pry-rails (0.3.9)
+      pry (>= 0.10.4)
+    pundit (2.1.0)
+      activesupport (>= 3.0.0)
+    racc (1.5.2)
+    rack (2.2.3)
+    rack-test (1.1.0)
+      rack (>= 1.0, < 3)
+    rails (6.1.4.1)
+      actioncable (= 6.1.4.1)
+      actionmailbox (= 6.1.4.1)
+      actionmailer (= 6.1.4.1)
+      actionpack (= 6.1.4.1)
+      actiontext (= 6.1.4.1)
+      actionview (= 6.1.4.1)
+      activejob (= 6.1.4.1)
+      activemodel (= 6.1.4.1)
+      activerecord (= 6.1.4.1)
+      activestorage (= 6.1.4.1)
+      activesupport (= 6.1.4.1)
+      bundler (>= 1.15.0)
+      railties (= 6.1.4.1)
+      sprockets-rails (>= 2.0.0)
+    rails-dom-testing (2.0.3)
+      activesupport (>= 4.2.0)
+      nokogiri (>= 1.6)
+    rails-html-sanitizer (1.4.2)
+      loofah (~> 2.3)
+    railties (6.1.4.1)
+      actionpack (= 6.1.4.1)
+      activesupport (= 6.1.4.1)
+      method_source
+      rake (>= 0.13)
+      thor (~> 1.0)
+    rainbow (3.0.0)
+    rake (13.0.6)
+    regexp_parser (2.1.1)
+    responders (3.0.1)
+      actionpack (>= 5.0)
+      railties (>= 5.0)
+    rexml (3.2.5)
+    rspec-core (3.10.1)
+      rspec-support (~> 3.10.0)
+    rspec-expectations (3.10.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.10.0)
+    rspec-mocks (3.10.2)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.10.0)
+    rspec-rails (5.0.1)
+      actionpack (>= 5.2)
+      activesupport (>= 5.2)
+      railties (>= 5.2)
+      rspec-core (~> 3.10)
+      rspec-expectations (~> 3.10)
+      rspec-mocks (~> 3.10)
+      rspec-support (~> 3.10)
+    rspec-support (3.10.2)
+    rubocop (1.20.0)
+      parallel (~> 1.10)
+      parser (>= 3.0.0.0)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 1.8, < 3.0)
+      rexml
+      rubocop-ast (>= 1.9.1, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 1.4.0, < 3.0)
+    rubocop-ast (1.11.0)
+      parser (>= 3.0.1.1)
+    rubocop-infinum (0.5.0)
+      rubocop
+      rubocop-performance
+      rubocop-rails
+      rubocop-rspec
+    rubocop-performance (1.11.5)
+      rubocop (>= 1.7.0, < 2.0)
+      rubocop-ast (>= 0.4.0)
+    rubocop-rails (2.11.3)
+      activesupport (>= 4.2.0)
+      rack (>= 1.1)
+      rubocop (>= 1.7.0, < 2.0)
+    rubocop-rake (0.6.0)
+      rubocop (~> 1.0)
+    rubocop-rspec (2.4.0)
+      rubocop (~> 1.0)
+      rubocop-ast (>= 1.1.0)
+    ruby-progressbar (1.11.0)
+    simplecov (0.21.2)
+      docile (~> 1.1)
+      simplecov-html (~> 0.11)
+      simplecov_json_formatter (~> 0.1)
+    simplecov-html (0.12.3)
+    simplecov_json_formatter (0.1.3)
+    sprockets (4.0.2)
+      concurrent-ruby (~> 1.0)
+      rack (> 1, < 3)
+    sprockets-rails (3.2.2)
+      actionpack (>= 4.0)
+      activesupport (>= 4.0)
+      sprockets (>= 3.0.0)
+    thor (1.1.0)
+    tzinfo (2.0.4)
+      concurrent-ruby (~> 1.0)
+    unicode-display_width (2.0.0)
+    uri_template (0.7.0)
+    websocket-driver (0.7.5)
+      websocket-extensions (>= 0.1.0)
+    websocket-extensions (0.1.5)
+    zeitwerk (2.4.2)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler-audit
+  factory_bot (~> 6.2)
+  faker (~> 2.18)
+  infinum_json_api_setup!
+  jsonapi-query_builder
+  jsonapi-serializer
+  overcommit (~> 0.58)
+  pg
+  pry-rails
+  pundit
+  rake
+  rspec-rails (~> 5.0)
+  rubocop (~> 1.0)
+  rubocop-infinum
+  rubocop-rake
+  simplecov
+
+BUNDLED WITH
+   2.1.4

data/README.md

@@ -0,0 +1,156 @@
+# Infinum JSON:API setup
+Preconfigured set of libraries for building JSON:API compliant endpoints, with matchers for writing more declarative JSON:API specs. This library presumes host project is compliant with using
+- [rails](https://github.com/rails/rails) as an application server
+- [jsonapi_parameters](https://github.com/visualitypl/jsonapi_parameters) for incoming data parsing
+- [json_schemer](https://github.com/davishmcclurg/json_schemer) for validating JSON structures
+- [responders](https://github.com/heartcombo/responders) for writing declarative actions
+
+## Installation
+1. Add Infinum JSON:API setup to your Gemfile
+  ```ruby
+  gem 'infinum_json_api_setup', github: 'infinum/infinum-json-api-setup'
+  ```
+
+2. Next, run the generator
+  ```bash
+  bundle exec rails generate infinum_json_api_setup:install
+  ```
+The generator will copy the [default translations](https://github.com/infinum/infinum-json-api-setup/blob/master/lib/generators/infinum_json_api_setup/templates/config/locales/json_api.en.yml) into the host project (`config/locales/json_api.en.yml`), where they can be customized.
+
+## Application configuration
+Create abstract class for your controllers, include common JSON:API request processing behaviour, and configure responders.
+```ruby
+module Api
+  class BaseController < ActionController::API
+    include InfinumJsonApiSetup::JsonApi::ErrorHandling
+    include InfinumJsonApiSetup::JsonApi::ContentNegotiation
+
+    self.responder = InfinumJsonApiSetup::JsonApi::Responder
+    respond_to :json_api
+  end
+end
+```
+
+## Basic usage
+
+### Permitted parameter handling
+Use [jsonapi_parameters](https://github.com/visualitypl/jsonapi_parameters) to transform incoming JSON:API compliant data into common Rails parameters
+```ruby
+def permitted_params
+  params.from_jsonapi
+        .require(:user)
+        .permit(:first_name, :last_name)
+end
+```
+
+### Responding
+Use `respond_with` to initiate transformation (serialization) of domain objects into HTTP response.
+```ruby
+def show
+  respond_with User.find(params[:id])
+end
+```
+
+`respond_with` is well integrated with `ActiveRecord::Model` interface. Given a compliant object, the method will correctly set a response status and handle object(or error) serialization based on the presence of `.errors`. For a successful domain operation, HTTP status will be 200 OK (or 201 in case of `create` controller action). Unsuccessful operations will have HTTP status 422 Unprocessable Entity with errors structured according to [JSON:API specification](https://jsonapi.org/format/#error-objects).
+```ruby
+def create
+  respond_with User.create(permitted_params)
+end
+```
+
+`respond_with` also detects usage from a `destroy` controller action and responds with HTTP status 204 No Content and an empty body.
+```ruby
+def destroy
+  respond_with User.destroy(params[:id])
+end
+```
+
+## Internals
+This section explains the under-the-hood behavior of the library.
+
+### Content negotiation
+`InfinumJsonApiSetup::JsonApi::ContentNegotiation` module is designed to integrate [server responsibilities](https://jsonapi.org/format/#content-negotiation-servers) of content negotiation protocol described by the JSON:API specification.
+
+### Error handling
+`InfinumJsonApiSetup::JsonApi::ErrorHandling` module is designed to catch and handle common exceptions that might bubble up when processing a request.
+
+| Exception                                      | HTTP status | Bugsnag notification |
+| ---                                            | :---:       | :---:                |
+| `ActionController::ParameterMissing`           | 400         |                      |
+| `ActionDispatch::Http::Parameters::ParseError` | 400         |                      |
+| `Jure::UnpermittedSortParameters`              | 400         | :white_check_mark:   |
+| `I18n::InvalidLocale`                          | 400         |                      |
+| `Pundit::NotAuthorizedError`                   | 403         | :white_check_mark:   |
+| `ActiveRecord::RecordNotFound`                 | 404         |                      |
+| `PG::Error`                                    | 500         |                      |
+
+### Error serialization
+`InfinumJsonApiSetup::JsonApi::ErrorSerializer` is responsible for serializing domain errors according to [JSON:API specification](https://jsonapi.org/format/#error-objects).
+
+## Testing
+
+### RSpec configuration
+Library ships with a set of declarative matchers and request/response helpers. To use them in your specs, configure your RSpec setup in the following way which
+- includes all defined matchers
+- includes request and response helper methods into specs tagged with `:request` metadata
+- configures search paths for resolving JSON schema files
+```ruby
+require 'infinum_json_api_setup/rspec'
+
+RSpec.configure do |config|
+  # Helpers
+  config.include InfinumJsonApiSetup::Rspec::Helpers::RequestHelper, type: :request
+  config.include InfinumJsonApiSetup::Rspec::Helpers::ResponseHelper, type: :request
+
+  # Schema paths
+  config.schema_response_root = Rails.application.root.join('path/to/response_schemas')
+  config.schema_request_root = Rails.application.root.join('path/to/request_schemas')
+end
+```
+### Matchers
+
+#### Have empty data
+```ruby
+expect(response).to have_empty_data
+```
+
+#### Have error pointer
+```ruby
+expect(response).to have_error_pointer('data/attributes/first_name')
+```
+
+#### Have resource count of
+```ruby
+expect(response).to have_resource_count_of(3)
+```
+
+#### Include all resource ids
+```ruby
+expect(response).to include_all_resource_ids(records.map(&:id))
+```
+
+#### Include all resource ids sorted
+```ruby
+expect(response).to include_all_resource_ids_sorted(records.map(&:id))
+```
+
+#### Include all resource string ids
+```ruby
+expect(response).to include_all_resource_string_ids(records.map(&:id).map(&:to_s))
+```
+
+#### Include error detail
+```ruby
+expect(response).to include_error_detail('name has been taken')
+```
+
+#### Include related resource
+```ruby
+expect(response).to include_related_resource('user', user.id)
+```
+
+## Credits
+**JSON:API setup** is maintained and sponsored by [Infinum](https://infinum.co)
+
+## License
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1 @@
+require 'bundler/gem_tasks'

data/bin/setup

@@ -0,0 +1,18 @@
+#!/usr/bin/env ruby
+require 'pathname'
+
+GEM_ROOT = Pathname.new File.expand_path('..', __dir__)
+DUMMY_APP_ROOT = Pathname.new File.expand_path('../spec/dummy', __dir__)
+
+Dir.chdir GEM_ROOT do
+  puts '== Installing dependencies =='
+  system 'gem install bundler --conservative'
+  system 'bundle check || bundle install'
+
+  puts '== Installing overcommit =='
+  system 'overcommit --install'
+end
+
+Dir.chdir DUMMY_APP_ROOT do
+  system 'bin/setup'
+end

data/infinum_json_api_setup.gemspec

@@ -0,0 +1,30 @@
+require File.expand_path('./lib/infinum_json_api_setup/version', __dir__)
+
+Gem::Specification.new do |s|
+  s.name        = 'infinum_json_api_setup'
+  s.version     = InfinumJsonApiSetup::VERSION
+  s.summary     = 'Infinum JSON:API setup'
+  s.description = 'Preconfigured setup for building JSON:API endpoints'
+  s.authors     = ['Team Backend @ Infinum']
+  s.email       = 'team.backend@infinum.com'
+  s.files       = `git ls-files`.split("\n")
+  s.homepage    = 'https://github.com/infinum/infinum-json-api-setup'
+  s.license     = 'MIT'
+  s.required_ruby_version = '> 2.7' # NOTE: randomly selected
+
+  s.add_runtime_dependency 'jsonapi_parameters' # TODO: define version
+  s.add_runtime_dependency 'json_schemer', '~> 0.2'
+  s.add_runtime_dependency 'pagy'               # TODO: define version
+  s.add_runtime_dependency 'rails'              # TODO: define version
+  s.add_runtime_dependency 'responders'         # TODO: define version
+
+  s.add_development_dependency 'jsonapi-query_builder'
+  s.add_development_dependency 'jsonapi-serializer'
+  s.add_development_dependency 'overcommit', '~> 0.58'
+  s.add_development_dependency 'pg'
+  s.add_development_dependency 'pry-rails'
+  s.add_development_dependency 'pundit'
+  s.add_development_dependency 'rake'
+  s.add_development_dependency 'rspec-rails', '~> 5.0'
+  s.add_development_dependency 'simplecov'
+end

data/lib/generators/infinum_json_api_setup/install_generator.rb

@@ -0,0 +1,12 @@
+module InfinumJsonApiSetup
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path('templates', __dir__)
+      desc 'Copy default translations'
+
+      def copy_locale
+        copy_file 'config/locales/json_api.en.yml', 'config/locales/json_api.en.yml'
+      end
+    end
+  end
+end

data/lib/generators/infinum_json_api_setup/templates/config/locales/json_api.en.yml

@@ -0,0 +1,21 @@
+en:
+  json_api:
+    errors:
+      bad_request:
+        title: Bad Request
+        detail: Bad request
+      not_found:
+        title: Not found
+        detail: Resource not found
+      forbidden:
+        title: Forbidden
+        detail: You are not allowed to perform this action
+      unauthorized:
+        title: Unauthorized
+        detail: Must be logged in to perform this action
+      unprocessable_entity:
+        title: Unprocessable Entity
+        detail: Cannot process request
+      internal_server_error:
+        title: Internal Server Error
+        detail: Something went wrong

data/lib/infinum_json_api_setup/error.rb

@@ -0,0 +1,61 @@
+module InfinumJsonApiSetup
+  module Error
+    class Base
+      # @return [String]
+      attr_reader :details
+
+      # @return [String]
+      attr_reader :title
+
+      # @param [Hash] opts
+      # @option opts [Object] :object
+      # @option opts [String] :message
+      def initialize(object: nil, message: nil)
+        @details =
+          details_from_object(object) || message || I18n.t("json_api.errors.#{http_status}.detail")
+        @title = I18n.t("json_api.errors.#{http_status}.title")
+      end
+
+      # @return [String]
+      def code
+        self.class.name.demodulize.underscore.upcase
+      end
+
+      # @return [Symbol]
+      def http_status
+        self.class.name.demodulize.underscore.to_sym
+      end
+
+      private
+
+      def details_from_object(object)
+        return unless object_supported?(object)
+
+        object.errors.map { |error| [error.attribute, error.full_message] }
+      end
+
+      def object_supported?(object)
+        object.present? && object.respond_to?(:errors) && object.errors.is_a?(ActiveModel::Errors)
+      end
+    end
+
+    class Forbidden < Base; end
+
+    class BadRequest < Base; end
+
+    class Gone < Base; end
+
+    class Unauthorized < Base; end
+
+    class UnprocessableEntity < Base; end
+
+    class InternalServerError < Base; end
+
+    class RecordNotFound < Base
+      # @return [Symbol]
+      def http_status
+        :not_found
+      end
+    end
+  end
+end