json_api_server 0.0.1

data/lib/json_api_server/builder.rb

@@ -0,0 +1,201 @@
+module JsonApiServer # :nodoc:
+  # This class integrates JSON API features -- pagination, sorting, filters, inclusion of
+  # related resources, and sparse fieldsets -- in one place. It collects data to be used
+  # by serializers.
+  #
+  # - It merges JSON API sub-queries (i.e, filters, pagination, sorting, etc.) into a query.
+  # - It provides convenience methods to requested sparse fields, includes and pagination.
+  #
+  # === Usage:
+  #
+  # The Builder class takes two arguments, (1) the controller request and (2) an
+  # initial query (i.e., MyModel.all, MyModel.authorized_to(current_user), etc.).
+  #
+  # Add JSON API features appropriate for the request. These methods are chainable.
+  # Except for sparse fields, JSON API features are configured; filter, include
+  # and sort configurations whitelist attributes/behavior while pagination sets
+  # defaults and limits on number of records to return.
+  #
+  # - <tt>add_pagination(pagination_options)</tt> - for collections
+  # - <tt>add_filter(filter_options)</tt> - for collections
+  # - <tt>add_include(include_options)</tt>
+  # - <tt>add_sort(sort_options)</tt> - for collections
+  # - <tt>add_fields</tt>
+  #
+  # Once features are added, their corresponding values can be accessed:
+  #
+  # - <tt>query</tt> - memoized merged query (merges initial request with sort, pagination, filters, includes sub-queries if any)
+  # - <tt>paginator</tt> - Paginator class for pagination links.
+  # - <tt>includes</tt> - Array of requested (whitelisted) includes (i.e, <tt>['comments', 'comment.author']</tt>)
+  # - <tt>sparse_fields</tt> - Hash of type/fields (i.e., {'articles => ['title', 'body', 'author'], 'people' => ['name']})
+  #
+  # ===== Example
+  #  attr_accessor :pagination_options, :sort_options, :filter_options, :include_options
+  #
+  #  before_action do |c|
+  #    c.pagination_options = { default_per_page: 10, max_per_page: 60 }
+  #    c.sort_options = {
+  #     permitted: [:character, :location, :published],
+  #     default: { id: :desc }
+  #    }
+  #    c.filter_options = [
+  #     { id: { type: 'Integer' } },
+  #     { published: { type: 'Date' } },
+  #     :location,
+  #     { book: { wildcard: :both } }
+  #    ]
+  #    c.include_options = [
+  #                          {'publisher': -> { includes(:publisher) }},
+  #                          {'comments': -> { includes(:comments) }},
+  #                         'comment.author'
+  #                       ]
+  #  end
+  #
+  #  # A collection.
+  #  def index
+  #    builder = JsonApiServer::Builder.new(request, Topic.current)
+  #     .add_pagination(pagination_options)
+  #     .add_filter(filter_options)
+  #     .add_include(include_options)
+  #     .add_sort(sort_options)
+  #     .add_fields
+  #
+  #   serializer = TopicsSerializer.from_builder(builder)
+  #   render json: serializer.to_json, status: :ok
+  #  end
+  #
+  #  # A resource.
+  #  def show
+  #    builder = JsonApiServer::Builder.new(request, Topic.find(params[:id]))
+  #     .add_include(['publisher', 'comments', 'comments.includes'])
+  #     .add_fields
+  #
+  #    serializer = TopicSerializer.from_builder(builder)
+  #    render json: serializer.to_json, status: :ok
+  #  end
+  #
+  class Builder
+    # ActionDispatch::Request passed in constructor.
+    attr_reader :request
+
+    # ActiveRecord::Base model extracted from initial query passed in constructor.
+    attr_reader :model
+
+    #  JsonApiServer::Fields instance if #add_fields was called. nil otherwise.
+    attr_reader :fields
+
+    # JsonApiServer::Pagination instance if #add_pagination was called. nil otherwise.
+    attr_reader :pagination
+
+    # JsonApiServer::Filter instance if #add_filter was called. nil otherwise.
+    attr_reader :filter
+
+    # JsonApiServer::Include instance if #add_include was called. nil otherwise.
+    attr_reader :include
+
+    # JsonApiServer::Sort instance if #add_sort was called. nil otherwise.
+    attr_reader :sort
+
+    # Arguments:
+    # - request - an ActionDispatch::Request
+    # - query (ActiveRecord::Relation) - Initial query.
+    def initialize(request, query)
+      @request = request
+      @initial_query = query
+      @model = model_from_query(@initial_query)
+    end
+
+    # Merges pagination, filter, sort, and include sub-queries (if defined)
+    # into the initial query. Returns an ActiveRecord::Relation object.
+    def relation
+      @relation ||= begin
+        return @initial_query unless @initial_query.respond_to?(:where)
+
+        %i[pagination filter include sort].each_with_object(@initial_query) do |method, query|
+          frag = send(method).try(:relation)
+          query.merge!(frag) if frag
+        end
+      end
+    end
+
+    alias query relation
+
+    # Creates JsonApiServer::Pagination instance based on request, initial query
+    # model and pagination options. Instance is available through
+    # the #pagination attribute. For collections only.
+    #
+    # - <tt>options</tt> - JsonApiServer::Pagination options.
+    def add_pagination(**options)
+      @pagination = JsonApiServer::Pagination.new(request, model, options)
+      self
+    end
+
+    # Creates JsonApiServer::Filter instance based on request, initial query
+    # model and filter configs. Instance is available through
+    # the #filter attribute.
+    #
+    # - <tt>permitted</tt> - JsonApiServer::Filter configs.
+    def add_filter(permitted = [])
+      @filter = JsonApiServer::Filter.new(request, model, permitted)
+      self
+    end
+
+    # Creates JsonApiServer::Include instance based on request, initial query
+    # model and include configs. Instance is available through
+    # the #include attribute.
+    #
+    # - <tt>permitted</tt> - JsonApiServer::Include configs.
+    def add_include(permitted = [])
+      @include = JsonApiServer::Include.new(request, model, permitted)
+      self
+    end
+
+    # Creates JsonApiServer::Sort instance based on request, initial query
+    # model and sort options. Instance is available through
+    # the #sort attribute.
+    #
+    # - <tt>options</tt> - JsonApiServer::Sort options.
+    def add_sort(**options)
+      @sort = JsonApiServer::Sort.new(request, model, options)
+      self
+    end
+
+    # Creates JsonApiServer::Fields instance based on request. Instance is
+    # available through the #fields attribute.
+    def add_fields
+      @fields = JsonApiServer::Fields.new(request)
+      self
+    end
+
+    # JsonApiServer::Paginator instance for collection if #add_pagination
+    # was called previously, nil otherwise.
+    def paginator
+      @pagination.try(:paginator_for, relation)
+    end
+
+    # (Array or nil) Whitelisted includes. An array of relationships (strings)
+    # if #add_include was called previously, nil otherwise.
+    # i.e,
+    #  ['comments', 'comments.author']
+    def includes
+      @include.try(:includes)
+    end
+
+    # (Hash or nil) Sparse fields. Available if #add_fields was previously called.
+    # i.e.,
+    #  {'articles => ['title', 'body', 'author'], 'people' => ['name']}
+    def sparse_fields
+      @fields.try(:sparse_fields)
+    end
+
+    protected
+
+    def model_from_query(query)
+      if query.respond_to?(:klass)
+        query.klass
+      elsif query.respond_to?(:class)
+        query.class
+      end
+    end
+  end
+end

data/lib/json_api_server/cast.rb

@@ -0,0 +1,89 @@
+require 'bigdecimal'
+require 'bigdecimal/util'
+require 'date_core' # DateTime
+
+#--
+# TODO: verify it works in Rails, esp in_time_zone.
+#++
+module JsonApiServer # :nodoc:
+  # Converts string params to data types.
+  class Cast
+    class << self
+      def to(value, type = 'String')
+        case type.to_s
+        when 'String'
+          apply_cast(value, :to_string)
+        when 'Integer'
+          apply_cast(value, :to_integer)
+        when 'Date'
+          apply_cast(value, :to_date)
+        when 'DateTime'
+          apply_cast(value, :to_datetime)
+        when 'Float'
+          apply_cast(value, :to_float)
+        when 'BigDecimal'
+          apply_cast(value, :to_decimal)
+        else
+          apply_cast(value, :to_string)
+        end
+      end
+
+      # Calls to_s on object.
+      def to_string(string)
+        string.to_s
+      end
+
+      # Calls to_i on object. Returns zero if it can't be converted.
+      def to_integer(string)
+        string.to_i
+      rescue
+        0
+      end
+
+      # Calls to_f on object. Returns zero if it can't be converted.
+      def to_float(string)
+        string.to_f
+      rescue
+        0.0
+      end
+
+      # Converts to BigDecimal and calls to_f on it. Returns
+      # zero if it can't be converted.
+      def to_decimal(string)
+        d = BigDecimal.new(string)
+        d.to_f
+      rescue
+        0.0
+      end
+
+      # Calls Date.parse on string.
+      # https://ruby-doc.org/stdlib-2.4.0/libdoc/date/rdoc/Date.html#method-c-parse
+      def to_date(string)
+        Date.parse(string)
+      rescue
+        nil
+      end
+
+      # Calls DateTime.parse on string. If datetime responds to
+      # :in_time_zone[http://apidock.com/rails/v4.2.1/ActiveSupport/TimeWithZone/in_time_zone)],
+      # it calls it.
+      def to_datetime(string)
+        d = DateTime.parse(string)
+        d.respond_to?(:in_time_zone) ? d.in_time_zone : d
+      rescue
+        nil
+      end
+
+      protected
+
+      # If val is an array, it casts each value. Otherwise, it casts the value.
+      def apply_cast(val, cast_method)
+        if val.respond_to?(:map)
+          val.map { |v| send(cast_method, v) }
+        else
+          send(cast_method, val)
+        end
+      end
+    end
+  end
+end

data/lib/json_api_server/configuration.rb

@@ -0,0 +1,99 @@
+module JsonApiServer # :nodoc:
+  # ==== Description
+  #
+  # Configurations for the gem.
+  #
+  # - Be sure to configure :base_url which defaults to nil.
+  # - Logger defaults to Logger.new(STDOUT). If using Rails, configure to Rails.logger.
+  # - Custom builders can be added to :filter_builders.
+  # - Default builders can be substituted.
+  #
+  # ===== Example
+  #
+  #   # config/initializers/json_api_server.rb
+  #
+  #   # example of custom filter builder
+  #   module JsonApiServer
+  #     class MyCustomFilter < FilterBuilder
+  #       def to_query(model)
+  #         model.where("#{column_name} LIKE :val", val: "%#{value}%")
+  #       end
+  #     end
+  #   end
+  #
+  #   JsonApiServer.configure do |c|
+  #     c.base_url = 'http://localhost:3001' # or ENV['HOSTNAME']
+  #     c.filter_builders = c.filter_builders
+  #       .merge({my_custom_builder: JsonApiServer::MyCustomFilter})
+  #     c.logger = Rails.logger
+  #   end
+  #
+  class Configuration
+    # Root url i.e., http://www.example.com. Used in pagination links.
+    attr_accessor :base_url
+
+    # Pagination option. Default maximum number of records to show per page.
+    # Defaults to 100.
+    attr_accessor :default_max_per_page
+
+    # Pagination option. Default number of records to show per page.
+    # Defaults to 20.
+    attr_accessor :default_per_page
+
+    # JSON is serialized with OJ gem. Options are defined in DEFAULT_SERIALIZER_OPTIONS.
+    attr_accessor :serializer_options
+
+    # Defaults to sql_like: JsonApiServer::SqlLike. If using Postgres,
+    # it can be replaced with pg_ilike: JsonApiServer::PgIlike.
+    attr_accessor :default_like_builder
+
+    # Defaults to sql_in: JsonApiServer::SqlIn. For IN (x,y,z) queries.
+    attr_accessor :default_in_builder
+
+    # Defaults to sql_comparison: JsonApiServer::SqlComp.
+    # For <,>, <=, >=, etc. queries.
+    attr_accessor :default_comparison_builder
+
+    # Defaults to sql_eql: JsonApiServer::SqlEql.
+    attr_accessor :default_builder
+
+    # Defaults to DEFAULT_FILTER_BUILDERS.
+    attr_accessor :filter_builders
+
+    # Defaults to Logger.new(STDOUT)
+    attr_accessor :logger
+
+    # Serializer options for the OJ gem.
+    DEFAULT_SERIALIZER_OPTIONS = {
+      escape_mode: :xss_safe,
+      time: :xmlschema,
+      mode: :compat
+    }.freeze
+
+    # Default filter builders. For generating queries based on
+    # on requested filters.
+    DEFAULT_FILTER_BUILDERS = {
+      sql_eql: JsonApiServer::SqlEql,
+      sql_comparison: JsonApiServer::SqlComp,
+      sql_in: JsonApiServer::SqlIn,
+      sql_like: JsonApiServer::SqlLike,
+      pg_ilike: JsonApiServer::PgIlike,
+      pg_jsonb_array: JsonApiServer::PgJsonbArray,
+      pg_jsonb_ilike_array: JsonApiServer::PgJsonbIlikeArray,
+      model_query: JsonApiServer::ModelQuery
+    }.freeze
+
+    def initialize
+      @base_url = nil
+      @default_max_per_page = 100
+      @default_per_page = 20
+      @default_like_builder = :sql_like
+      @default_in_builder = :sql_in
+      @default_comparison_builder = :sql_comparison
+      @default_builder = :sql_eql
+      @serializer_options = DEFAULT_SERIALIZER_OPTIONS
+      @filter_builders = DEFAULT_FILTER_BUILDERS
+      @logger = Logger.new(STDOUT)
+    end
+  end
+end

data/lib/json_api_server/controller/error_handling.rb

@@ -0,0 +1,164 @@
+module JsonApiServer # :nodoc:
+  module Controller # :nodoc:
+    # Handles common controller errors. Returns JsonApi errors http://jsonapi.org/format/#errors.
+    #
+    # === Usage
+    #
+    # To use, include the JsonApiServer::Controller::ErrorHandling module in your
+    # base API controller class:
+    #
+    #   i.e.,
+    #
+    #   class Api::BaseController < ApplicationController
+    #     include JsonApiServer::Controller::ErrorHandling
+    #   end
+    #
+    # === I18n
+    #
+    # Messages are defined in config/locales/en.yml.
+    #
+    # Customize ActiveRecord::RecordNotFound and ActiveRecord::RecordNotUnique
+    # messages to reference a resource by name.
+    #
+    # *Example:*
+    #
+    #  # Given a sandwiches controller...
+    #  class Api::V1::SandwichesController < Api::BaseController
+    #      ...
+    #  end
+    #
+    #  # config/locales/en.yml
+    #  en:
+    #    json_api_server:
+    #      controller:
+    #        sandwiches:
+    #          name: 'sandwich'
+    #
+    #  # messages now become:
+    #  # 404 => "This sandwich does not exist."
+    #  # 409 => "This sandwich already exists."
+    module ErrorHandling
+      def self.included(base)
+        # Overrides of exception handling.
+        base.rescue_from StandardError, with: :render_500
+        base.rescue_from JsonApiServer::BadRequest, with: :render_400
+        base.rescue_from ActionController::BadRequest, with: :render_400
+        base.rescue_from ActiveRecord::RecordNotFound, with: :render_404
+        base.rescue_from ActiveRecord::RecordNotUnique, with: :render_409
+        base.rescue_from ActionController::RoutingError, with: :render_404
+        base.rescue_from ActionController::UrlGenerationError, with: :render_404
+        base.rescue_from ActionController::UnknownController, with: :render_404
+        base.rescue_from ActionController::UnknownFormat, with: :render_unknown_format
+      end
+
+      protected
+
+      # Render 400 json and status.
+      def render_400(exception = nil)
+        message = (exception && known?(exception) && exception.message) || I18n.t('json_api_server.render_400.detail')
+        errors = JsonApiServer.errors(
+          status: 400,
+          title: I18n.t('json_api_server.render_400.title'),
+          detail: message
+        )
+        render json: errors.to_json, status: 400
+      end
+
+      # Render 401 json and status.
+      def render_401
+        errors = JsonApiServer.errors(
+          status: 401,
+          title:  I18n.t('json_api_server.render_401.title'),
+          detail: I18n.t('json_api_server.render_401.detail')
+        )
+        render json: errors.to_json, status: 401
+      end
+
+      # Render 403 json and status.
+      def render_403
+        errors = JsonApiServer.errors(
+          status: 403,
+          title: I18n.t('json_api_server.render_403.title'),
+          detail: I18n.t('json_api_server.render_403.detail')
+        )
+        render json: errors.to_json, status: 403
+      end
+
+      # Render 404 json and status. Message customizable (see class description).
+      def render_404(_exception = nil)
+        errors = JsonApiServer.errors(
+          status: 404,
+          title: I18n.t('json_api_server.render_404.title'),
+          detail: I18n.t('json_api_server.render_404.detail', name: _i18n_name)
+        )
+        render json: errors.to_json, status: 404
+      end
+
+      # Render 409 json and status. Message customizable (see class description).
+      def render_409(_exception = nil)
+        errors = JsonApiServer.errors(
+          status: 409,
+          title: I18n.t('json_api_server.render_409.title'),
+          detail: I18n.t('json_api_server.render_409.detail', name: _i18n_name)
+        )
+        render json: errors.to_json, status: 409
+      end
+
+      # Render 422 json and status. For model validation error.
+      def render_422(object)
+        errors = JsonApiServer.validation_errors(object)
+        render json: errors.to_json, status: 422
+      end
+
+      # Render 500 json. Logs exception.
+      def render_500(exception = nil)
+        JsonApiServer.logger.error(exception.try(:message))
+        JsonApiServer.logger.error(exception.try(:backtrace))
+
+        errors = JsonApiServer.errors(
+          status: 500,
+          title: I18n.t('json_api_server.render_500.title'),
+          detail: I18n.t('json_api_server.render_500.detail')
+        )
+        render json: errors.to_json, status: 500
+      end
+
+      # Render 406 status code and message that the format is not supported.
+      def render_unknown_format
+        format = sanitize(params[:format]) || ''
+        errors = JsonApiServer.errors(
+          status: 406,
+          title: I18n.t('json_api_server.render_unknown_format.title'),
+          detail: I18n.t('json_api_server.render_unknown_format.detail', name: format)
+        )
+        render json: errors.to_json, status: 406
+      end
+
+      # Render 503 json and status (service unavailable).
+      def render_503(message = nil)
+        errors = JsonApiServer.errors(
+          status: 500,
+          title: I18n.t('json_api_server.render_503.title'),
+          detail: message || I18n.t('json_api_server.render_503.detail')
+        )
+        render json: errors.to_json, status: 503
+      end
+
+      private
+
+      def known?(exception)
+        !(exception.class.name =~ /JsonApiServer::BadRequest/).nil?
+      end
+
+      def sanitize(string)
+        ActionController::Base.helpers.sanitize(string.to_s)
+      end
+
+      def _i18n_name
+        I18n.t("json_api_server.controller.#{controller_name}.name", raise: true)
+      rescue
+        I18n.t('json_api_server.variables.defaults.name')
+      end
+    end
+  end
+end