simple_jsonapi_rails 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: eb87c3e8f49a4ea784c1aafacf83f82dd69f35ee
+  data.tar.gz: 32c513cf1c662eebf42af0a1bc05b3feca0f8ad5
+SHA512:
+  metadata.gz: c1f9d71e8dc53a740a449b48e978a4eff6e14a78cb3a8fa23fd235f0109e9250bb2789045b80daf45bde389c09b26ab3d9320832b9a60f72ba3144ed2b05e121
+  data.tar.gz: eaa046434edc39bd0ee5237dd48845a15acf178da2d76b40c9c7545ca0915ba749c811dbb28df3b3902f37a3fad01fc6faeede4228b5972931a4f61eafdfc7c6

data/.gitignore

@@ -0,0 +1,10 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/Gemfile.lock
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.gem

data/.rubocop.yml

@@ -0,0 +1,132 @@
+AllCops:
+  Exclude:
+    - '*.gemspec'
+    - 'Gemfile*'
+    - 'test/dummy/**/*'
+  TargetRubyVersion: "2.3"
+
+# Do not modify any of these rules without running your changes past the `@techleads` Slack group.
+
+# In order to make CodeClimate run in less than 30 minutes (the time-out), we're temporarily turning off
+# some of the low-risk, high-frequency cops.  This should be a temporary solution.  We should either
+# fix all of these issues across the codebase, or tune the cops to only pull up these issues when they
+# matter (e.g. setting the max line length to 120 instead of 80)
+
+Style/StringLiterals:
+  Enabled: false # this cop slows rubocop down too much so CodeClimate times out
+  EnforcedStyle: double_quotes
+
+Style/NumericLiterals:
+  Enabled: false # this cop slows rubocop down too much so CodeClimate times out
+
+# Permanent rules below
+
+Layout/AlignParameters:
+  Enabled: false # we haven't reached consensus yet on what this rule should be
+
+Layout/CaseIndentation:
+  EnforcedStyle: end
+  IndentOneStep: false
+
+# Layout/ElseAlignment:
+#   Enabled: false # we haven't reached consensus yet on what this rule should be
+
+# Layout/MultilineMethodCallIndentation:
+#   Enabled: false # we haven't reached consensus yet on what this rule should be
+
+Layout/MultilineOperationIndentation:
+  Enabled: true
+  EnforcedStyle: indented
+
+Lint/AmbiguousRegexpLiteral:
+  Enabled: false # we disagree with this rule
+
+# Lint/EndAlignment:
+#   EnforcedStyleAlignWith: start_of_line
+
+Metrics/AbcSize:
+  # There are ~500 methods > 20 as of 3/7/18, vs. ~900 methods > 15 (which is the default)
+  Max: 20
+
+Metrics/BlockLength:
+  Max: 25
+  ExcludedMethods: ["class_methods", "describe", "included"]
+
+Metrics/ClassLength:
+  # nearly all classes over 200 lines are old and crufty and should be split up
+  Max: 200
+
+Metrics/CyclomaticComplexity:
+  # There are ~100 methods > 8 as of 3/7/18, vs. 220 > 6 (which is the default)
+  Max: 8
+
+Metrics/LineLength:
+  # There are 23k lines > 80 chars, 5k > 120, 2k > 140 chars as of 12/21/17
+  Max: 120
+
+Metrics/MethodLength:
+  # There are ~100 methods > 35 lines as of 12/21/17
+  Max: 35
+
+Metrics/ModuleLength:
+  # nearly all modules over 200 lines are old and crufty and should be split up
+  Max: 200
+
+Metrics/PerceivedComplexity:
+  # There are ~100 methods > 8 as of 3/7/18, vs. ~150 methods > 7 (which is the default)
+  Max: 8
+
+Naming/VariableNumber:
+  EnforcedStyle: snake_case # `condition_info_1` is easier to read than `condition_info1`
+
+Performance/Casecmp:
+  Enabled: false # we generally prefer the readability of downcase over the performance of casecmp
+
+Style/Alias:
+  EnforcedStyle: prefer_alias_method
+
+Style/BracesAroundHashParameters:
+  Enabled: false # using braces can be a good choice, e.g., `assert_equal expected_json, { "foo" => "bar" }`
+
+Style/ClassAndModuleChildren:
+  EnforcedStyle: compact
+  Exclude: ["share/**/*"]
+
+Style/CollectionMethods:
+  Enabled: true
+  PreferredMethods:
+    collect: map
+    collect!: map!
+    inject: reduce
+    detect: find
+    find_all: select
+
+Style/Documentation:
+  Enabled: false # don't require class and method doc comments
+
+Style/EmptyMethod:
+  EnforcedStyle: expanded
+
+Style/FrozenStringLiteralComment:
+  EnforcedStyle: never
+
+Style/GuardClause:
+  Enabled: false # sometimes guard clauses are appropriate and sometimes they aren't
+
+Style/IfUnlessModifier:
+  Enabled: false # sometimes its clearer to use traditional if/end conditionals, even if they would fit on one line
+
+Style/NumericPredicate:
+  Enabled: false # we disagree with this rule
+
+Style/SymbolArray:
+  Enabled: false # undecided
+
+Style/TrailingCommaInArguments:
+  EnforcedStyleForMultiline: consistent_comma
+
+Style/TrailingCommaInLiteral:
+  EnforcedStyleForMultiline: consistent_comma
+
+Style/WordArray:
+  Enabled: false # sometimes %w makes sense and sometimes it doesn't

data/CHANGELOG.md

@@ -0,0 +1,2 @@
+## Version 1.0.0 - April 19, 2018
+* Initial public release

data/Gemfile

@@ -0,0 +1,5 @@
+source 'https://rubygems.org'
+
+gemspec
+
+gem 'rake'

data/Jenkinsfile

@@ -0,0 +1,92 @@
+pipeline {
+  agent none
+  options {
+    timeout(time: 1, unit: 'HOURS')
+    skipDefaultCheckout()
+  }
+
+  stages {
+    stage("Build Ruby") {
+      agent {
+        node {
+          label 'docker'
+        }
+      }
+
+      steps {
+        script {
+          with_ruby_build() {
+            script {
+              uid = sh(returnStdout: true, script: 'stat -c %g .').trim()
+              gid = sh(returnStdout: true, script: 'stat -c %u .').trim()
+            }
+
+            sh "chown -R ${uid}:${gid} vendor/bundle/"
+            sh "rm -rf vendor/bundle/ruby/2.3.0/cache"
+            stash name: 'ruby-bundle', includes: 'vendor/bundle/'
+          }
+        }
+      }
+    }
+
+    stage("Test") {
+      steps {
+        script {
+          node('docker') {
+            checkout([
+              $class: 'GitSCM',
+              branches: scm.branches,
+              doGenerateSubmoduleConfigurations: scm.doGenerateSubmoduleConfigurations,
+              extensions: scm.extensions + [[$class: 'CloneOption', noTags: true, reference: '', shallow: true]],
+              userRemoteConfigs: scm.userRemoteConfigs
+            ])
+            try {
+              docker.image('ruby:2.3.3').inside() {
+                sh 'rm -rf vendor/bundle'
+                unstash 'ruby-bundle'
+                sh 'bundle install --path=vendor/bundle'
+
+                withEnv([
+                  'DISABLE_SPRING=1',
+                  'TZ=America/New_York'
+                ]) {
+                  sh 'bundle exec rake test'
+                }
+              }
+            }
+            finally {
+              junit 'test/reports/'
+              cleanWs()
+            }
+          }
+        }
+      }
+    }
+  }
+
+  post {
+    failure {
+      script {
+        if (env.BRANCH_NAME == 'master' || env.BRANCH_NAME == 'current') {
+          slackSend (channel: '#plm_website', color: '#FF0000', message: "FAILED ${env.JOB_NAME} [${env.BUILD_NUMBER}] (${env.RUN_DISPLAY_URL})")
+        }
+      }
+    }
+  }
+}
+
+def with_ruby_build(closure) {
+  docker.image('ruby:2.3.3').inside() {
+    checkout([
+      $class: 'GitSCM',
+      branches: scm.branches,
+      doGenerateSubmoduleConfigurations: scm.doGenerateSubmoduleConfigurations,
+      extensions: scm.extensions + [[$class: 'CloneOption', noTags: true, reference: '', shallow: true]],
+      userRemoteConfigs: scm.userRemoteConfigs
+    ])
+    sh 'rm -rf vendor/bundle'
+    sh 'bundle install --path=vendor/bundle'
+    closure()
+    cleanWs()
+  }
+}

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2016-2018 PatientsLikeMe
+
+MIT License
+
+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 @@
+# SimpleJsonapi/Rails
+
+A library for integrating SimpleJsonapi into a Rails application.
+
+## Installation
+
+Add **simple\_jsonapi\_rails** to your Gemfile and include **SimpleJsonapi::Rails::ActionController** in your API controllers:
+
+```ruby
+# Gemfile
+gem 'simple_jsonapi_rails'
+
+# app/controllers/api_controller.rb
+class ApiController < ApplicationController
+  include SimpleJsonapi::Rails::ActionController
+end
+```
+
+## Controllers, parsing, and rendering
+
+### Index actions
+
+Render a collection of resources with **`render jsonapi_resources:`**.
+
+```ruby
+class OrdersController < ApiController
+  def index
+    orders = Order.all  # search, sort, paginate, etc.
+    render jsonapi_resources: orders
+  end
+end
+```
+
+Any additional parameters will be passed through to the serializer.
+
+```ruby
+class OrdersController < ApiController
+  def index
+    orders = Order.all
+    render jsonapi_resources: orders,
+      serializer: OrderSerializer,
+      fields: jsonapi.fields_params,
+      include: jsonapi.include_params,
+      sort_related: jsonapi.sort_related_params,
+      links: { self: "https://example.com/orders" },
+      meta: { generated_at: Time.current },
+      extras: { current_user: @current_user }
+  end
+end
+```
+
+### Show actions
+
+Render a single resource with **`render jsonapi_resource:`**. Any additional parameters will be passed through to the serializer.
+
+```ruby
+class OrdersController < ApiController
+  def show
+    order = Order.find(params[:id])
+    render jsonapi_resource: order,
+      serializer: OrderSerializer,
+      ...
+  end
+end
+```
+
+### Create and update actions
+
+Incoming JSON:API documents can be parsed into a more Rails-friendly structure by calling **`jsonapi_deserialize`** in the controller class.
+
+`jsonapi_deserialize` converts this incoming document ...
+
+```json
+{
+  "data": {
+    "type": "orders",
+    "id": "1",
+    "attributes": {
+      "customer_name": "Jose",
+      "date": "2017-10-01",
+    },
+    "relationships": {
+      "customer": {
+        "data": { "type": "customers", "id": "11" }
+      },
+      "products": {
+        "data": [
+          { "type": "products", "id": "21" },
+          { "type": "widgets", "id": "22" },
+        ]
+      },
+    },
+  }
+}
+```
+
+... to this hash ...
+
+```ruby
+{
+  type: "orders",
+  id: "1",
+  customer_name: "Jose",
+  date: "2017-10-01",
+  customer_type: "customers",
+  customer_id: "11",
+  product_types: ["products", "widgets"],
+  product_ids: ["21", "22"],
+}
+```
+
+... which can then be saved with typical Rails actions.
+
+```ruby
+class OrdersController < ApiController
+  jsonapi_deserialize :order, only: [:create, :update]
+
+  def create
+    order = Order.create!(order_params)
+    render jsonapi_resource: order, status: :created
+  end
+
+  def update
+    order = Order.find(params[:id]).update!(order_params)
+    render jsonapi_resource: order, status: :ok
+  end
+
+  private
+  def order_params
+    params.require(:order).permit(:customer_name, :date)
+  end
+end
+```
+
+Note the use of bang methods (`#create!` and `#update!`). While not necessary, `ActiveRecord::RecordNotFound`, `::RecordInvalid`, and `::RecordNotSaved` exceptions will be rescued and rendered automatically.
+
+You can also render errors explicitly with **`render jsonapi_errors:`**.
+
+```ruby
+class OrdersController < ApiController
+  jsonapi_deserialize :order, only: [:create, :update]
+
+  def create
+    order = Order.new(order_params)
+    if order.save
+      render jsonapi_resource: order, status: :created
+    else
+      error = SimpleJsonapi::Errors::WrappedError.new(...)
+      render jsonapi_errors: error, status: :unprocessable_entity
+    end
+  end
+end
+```
+
+## Error handling
+
+In addition to restructuring the incoming JSON, `jsonapi_deserialize` also stores a collection of pointers that can be used to render errors.
+
+Calling **`jsonapi.pointers`** in a controller action returns the following structure.
+
+```ruby
+# OrdersController#create
+jsonapi.pointers
+=> {
+  type: "/data/type",
+  id: "/data/id",
+  customer_name: "/data/attributes/customer_name",
+  date: "/data/attributes/date",
+  customer_type: "/data/relationships/customer",
+  customer_id: "/data/relationships/customer",
+  product_types: "/data/relationships/products",
+  product_ids: "/data/relationships/products",
+}
+```
+
+SimpleJsonapi/Rails also provides helpers for rendering several Rails-specific errors.
+
+**`SimpleJsonapi::Errors::ActiveModelError`** converts an `ActiveModel::Errors` object to an array of serializable errors. This is done automatically in response to `AR::RecordInvalid` or `AR::RecordNotSaved`.
+
+```ruby
+SimpleJsonapi::Errors::ActiveModelError.from_errors(order.errors, jsonapi.pointers)
+=> [
+  <SimpleJsonapi::Errors::ActiveModelError
+     status: "422",
+     code:   "unprocessable_entity",
+     title:  "Invalid customer_name",
+     detail: "Customer name must be present",
+     source: { pointer: "/data/attributes/customer_name" }
+  >, ...
+]
+```
+
+A serializer is provided for `ActiveRecord::RecordNotFound` errors, so they can be rendered directly.
+
+```ruby
+error = ActiveRecord::RecordNotFound.new(...)
+render jsonapi_errors: error, status: :not_found
+```
+
+## Request Validation
+
+SimpleJsonapi/Rails performs some basic request validations via two `before_action`s,
+`validate_jsonapi_request_headers`, and `validate_jsonapi_request_body`.
+
+The `Content-Type` header must be set to `application/vnd+api.json` if there is a response body present. If it is not a
+head response will be returned with status 415 Unsupported Media Type.
+
+The `Accept` header, if it present, must also be set to `application/vnd+api.json`. If it is not a head response will be
+returned with status 406 Not Acceptable.
+
+## Routing
+Rails' route mapper works well for most jsonapi resource routes. However, simple_jsonapi_rails does supply helpers method
+for defining relationship routes, which can be trickier:
+
+```ruby
+# config/routes.rb
+resources :orders do
+  jsonapi_to_many_relationship(:orders, :items)
+  jsonapi_to_one_relationship(:orders, :customer)
+end
+```
+
+This code generates the following paths and routes/controller action mappings.
+```
+orders_relationships_items    POST   /orders/:order_id/relationships/items(.:format)   orders/relationships/items#add
+orders_relationships_items    DELETE /orders/:order_id/relationships/items(.:format)   orders/relationships/items#remove
+orders_relationships_items    PATCH  /orders/:order_id/relationships/items(.:format)   orders/relationships/items#replace
+
+orders_relationships_customer PATCH  /orders/:order_id/customer(.:format)              orders/relationships/customer#replace
+
+```
+
+## Running tests
+
+1. Change to the gem's directory
+2. Run `bundle install`
+3. Run `bundle exec rake test`
+
+## Release Process
+Once pull request is merged to master, on latest master:
+1. Update CHANGELOG.md. Version: [ major (breaking change: non-backwards
+   compatible release) | minor (new features) | patch (bugfixes) ]
+2. Update version in lib/global_enforcer/version.rb
+3. Release by running `bundle exec rake release`
+

data/Rakefile

@@ -0,0 +1,10 @@
+require 'bundler/gem_tasks'
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.libs << 'lib'
+  t.test_files = FileList['test/**/*_test.rb']
+end
+
+task default: :test

data/lib/simple_jsonapi/errors/active_model_error.rb

@@ -0,0 +1,21 @@
+module SimpleJsonapi
+  module Errors
+    class ActiveModelError
+      def self.from_errors(errors, pointer_mapping = {})
+        errors.keys.flat_map do |attribute|
+          errors.full_messages_for(attribute).map do |message|
+            new(attribute, message, pointer_mapping[attribute])
+          end
+        end
+      end
+
+      attr_reader :attribute, :message, :pointer
+
+      def initialize(attribute, message, pointer)
+        @attribute = attribute.to_s
+        @message = message.to_s
+        @pointer = pointer.to_s
+      end
+    end
+  end
+end

data/lib/simple_jsonapi/errors/active_model_error_serializer.rb

@@ -0,0 +1,15 @@
+module SimpleJsonapi
+  module Errors
+    class ActiveModelErrorSerializer < ErrorSerializer
+      status "422"
+      code "unprocessable_entity"
+
+      title { |err| "Invalid #{err.attribute.presence || 'record'}" }
+      detail { |err| err.message }
+
+      source do
+        pointer(if: ->(err) { err.pointer.present? }) { |err| err.pointer }
+      end
+    end
+  end
+end

data/lib/simple_jsonapi/errors/active_record/record_not_found_serializer.rb

@@ -0,0 +1,15 @@
+module SimpleJsonapi
+  module Errors
+    module ActiveRecord
+      class RecordNotFoundSerializer < SimpleJsonapi::ErrorSerializer
+        status "404"
+        code "not_found"
+        title "Not found"
+        detail { |ex| ex.message }
+        source do
+          parameter { |ex| ex.primary_key }
+        end
+      end
+    end
+  end
+end