json_api_server 0.0.1

data/Rakefile

@@ -0,0 +1,6 @@
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require 'bundler/setup'
+require 'json_api_server'
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require 'irb'
+IRB.start

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/config/locales/en.yml

@@ -0,0 +1,32 @@
+en:
+  json_api_server:
+    variables:
+      defaults:
+        name: 'resource'
+    render_400:
+      title: 'Bad Request'
+      detail: "You've made an invalid request."
+      inclusion: "Inclusion param '%{param}' is not supported."
+      filter: "Filter param '%{param}' is not supported."
+      sort: "Sort param '%{param}' is not supported."
+    render_401:
+      title: 'Unauthorized'
+      detail: 'Authentication failed.'
+    render_403:
+      title: 'Forbidden'
+      detail: 'Unauthorized to access this resource or perform this action.'
+    render_404:
+      title: 'Not Found'
+      detail: "This %{name} does not exist."
+    render_409:
+      title: 'Conflict'
+      detail: "This %{name} already exists."
+    render_500:
+      title: 'Internal Server Error'
+      detail: 'The server encountered an unexpected error.'
+    render_503:
+      title: 'Service Unavailable'
+      detail: 'The service is unavailable. It may be under maintenance or preparing for maintenance.'
+    render_unknown_format:
+      title: 'Unknown Format'
+      detail: "Format %{name} is not supported for this endpoint."

data/docker-compose.yml

@@ -0,0 +1,10 @@
+# docker-compose run --rm gem
+version: '2'
+services:
+  gem:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    volumes:
+      - .:/home/gems/mygem
+    entrypoint: /bin/bash

data/json_api_server.gemspec

@@ -0,0 +1,50 @@
+# coding: utf-8
+
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'json_api_server/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'json_api_server'
+  spec.version       = JsonApiServer::VERSION
+  spec.authors       = ['ed.mare']
+
+  spec.summary       = 'Implements JSON API 1.0 - data, errors, meta, pagination, sort, ' \
+                        'filters, sparse fieldsets and inclusion of related resources.'
+  spec.description   = 'For building JSON APIs.'
+  spec.homepage      = 'https://github.com/ed-mare/json_api_server'
+  spec.license       = 'MIT'
+
+  # Prevent pushing this gem to RubyGems.org. To allow pushes either set the 'allowed_push_host'
+  # to allow pushing to a single host or delete this section to allow pushing to any host.
+  if spec.respond_to?(:metadata)
+    spec.metadata['allowed_push_host'] = "https://rubygems.org"
+  else
+    raise 'RubyGems 2.0 or newer is required to protect against ' \
+      'public gem pushes.'
+  end
+
+  spec.files = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+  spec.required_ruby_version = '>= 2.1'
+
+  spec.rdoc_options += ['--main', 'README.md', '--exclude', 'spec', '--exclude', 'bin', '--exclude', 'Dockerfile',
+                        '--exclude', 'Gemfile', '--exclude', 'Gemfile.lock', '--exclude', 'Rakefile']
+
+  spec.add_dependency 'oj', '~> 3.0'
+  spec.add_dependency 'railties', '>= 5.0'
+  spec.add_dependency 'activesupport', '>= 5.0'
+  spec.add_dependency 'will_paginate', '~> 3.1.0' # for Rails 3+, Sinatra, and Merb
+
+  spec.add_development_dependency 'bundler', '>= 1.13'
+  spec.add_development_dependency 'sqlite3'
+  spec.add_development_dependency 'rake', '>= 10.0'
+  spec.add_development_dependency 'rspec', '>= 3.0'
+  spec.add_development_dependency 'rails', '>= 4.1'
+  spec.add_development_dependency 'rspec-rails', '>= 3.5'
+  spec.add_development_dependency 'rubocop', '>= 0.47'
+end

data/lib/json_api_server.rb

@@ -0,0 +1,76 @@
+require 'oj'
+require 'will_paginate'
+require 'logger'
+require 'active_support/core_ext/module/delegation'
+require 'active_support/core_ext/object/blank'
+require 'active_support/core_ext/object/try'
+require 'active_support/core_ext/hash'
+require 'active_support/inflector'
+
+require 'json_api_server/version'
+require 'json_api_server/api_version'
+require 'json_api_server/exceptions'
+require 'json_api_server/filter_builders'
+require 'json_api_server/configuration'
+require 'json_api_server/meta_builder'
+require 'json_api_server/serializer'
+require 'json_api_server/base_serializer'
+require 'json_api_server/resource_serializer'
+require 'json_api_server/resources_serializer'
+require 'json_api_server/attributes_builder'
+require 'json_api_server/relationships_builder'
+require 'json_api_server/error'
+require 'json_api_server/errors'
+require 'json_api_server/validation_errors'
+require 'json_api_server/paginator'
+require 'json_api_server/pagination'
+require 'json_api_server/sort_configs'
+require 'json_api_server/sort'
+require 'json_api_server/fields'
+require 'json_api_server/cast'
+require 'json_api_server/filter_config'
+require 'json_api_server/filter_parser'
+require 'json_api_server/filter'
+require 'json_api_server/include'
+require 'json_api_server/builder'
+
+if defined?(Rails)
+  require 'json_api_server/engine'
+  require 'json_api_server/mime_types'
+  require 'json_api_server/controller/error_handling'
+
+  # https://github.com/ohler55/oj/blob/master/pages/Rails.md
+  # gem 'oj_mimic_json' # we need this for Rails 4.1.x
+  Oj.optimize_rails if Oj.respond_to?(:optimize_rails) # rails 5 but also rails 4?
+end
+
+module JsonApiServer # :nodoc:
+  class << self
+    attr_writer :configuration
+
+    def configuration
+      @configuration ||= JsonApiServer::Configuration.new
+    end
+
+    def configure
+      yield configuration
+    end
+
+    def errors(errors)
+      JsonApiServer::Errors.new(errors)
+    end
+
+    def validation_errors(model)
+      JsonApiServer::ValidationErrors.new(model)
+    end
+
+    def paginator(current_page, total_pages, per_page, base_url, params = {})
+      JsonApiServer::Paginator.new(current_page, total_pages, per_page, base_url, params)
+    end
+
+    # Convenience method to JsonApiServer.configuration.logger.
+    def logger
+      JsonApiServer.configuration.logger
+    end
+  end
+end

data/lib/json_api_server/api_version.rb

@@ -0,0 +1,8 @@
+module JsonApiServer # :nodoc:
+  # JSON API version number. Currently 1.0.
+  module ApiVersion
+    def jsonapi
+      { 'version' => '1.0' }
+    end
+  end
+end

data/lib/json_api_server/attributes_builder.rb

@@ -0,0 +1,135 @@
+module JsonApiServer # :nodoc:
+  # Related to sparse fieldsets. http://jsonapi.org/format/#fetching-sparse-fieldsets
+  # "A client MAY request that an endpoint return only specific fields in the response on a per-type
+  # basis by including a fields[TYPE] parameter."
+  #
+  # Use this class to build the <tt>attributes</tt> section in JSON API
+  # serializers. It will only add attributes defined in #fields (sparse fieldset).
+  # If #fields is nil (no requested sparse fieldset), it will add all attributes.
+  #
+  # ==== Examples
+  #
+  # This:
+  #  /articles?include=author&fields[articles]=title,body,phone&fields[people]=name
+  #
+  # converts to:
+  #   {'articles' => ['title', 'body', 'phone'], 'people' => ['name']}
+  #
+  # When <tt>fields</tt> is an array, only fields in the array are added:
+  #
+  #  AttributesBuilder.new(['title', 'body', 'phone'])
+  #    .add('title', @record.title)
+  #    .add('body',  @record.body)
+  #    .add_if('phone', @record.phone, -> { admin? })  # conditionally adding
+  #    .add('isbn', @record.isbn)  # not in sparse fields array
+  #    .attributes
+  #
+  #    # when non-admin
+  #    # => {
+  #    #      'title' => 'Everyone Poops',
+  #    #      'body' => 'Taro Gomi'
+  #    #   }
+  #
+  #    #    or...
+  #
+  #    # when admin
+  #    # => {
+  #    #      'title' => 'Everyone Poops',
+  #    #       'body' => 'Taro Gomi',
+  #    #       'phone' => '123-4567',
+  #    #   }
+  #
+  # When <tt>fields</tt> is nil, all attributes are added.
+  #
+  #   AttributesBuilder.new
+  #    .add_multi(@record, 'title', 'body')
+  #    .add_if('phone', @record.phone, -> { admin? })  # conditionally adding
+  #    .add('isbn', @record.isbn)
+  #    .attributes
+  #
+  #    # when non-admin
+  #    # => {
+  #    #      'title' => 'Everyone Poops',
+  #    #      'body' => 'Taro Gomi',
+  #    #      'isbn' => '5555555'
+  #    #    }
+  #
+  #    #    or...
+  #
+  #    # when admin
+  #    # => {
+  #    #       'title' => 'Everyone Poops',
+  #    #       'body' => 'Taro Gomi',
+  #    #       'phone' => '123-4567',
+  #    #       'isbn' => '5555555'
+  #    #    }
+  #
+  class AttributesBuilder
+    # (Array or nil) fields (sparse fieldset) array passed in initialize.
+    attr_reader :fields
+
+    # * <tt>fields</tt> - Array of fields to display for a type. Defaults to nil. When nil, all fields are permitted.
+    def initialize(fields = nil)
+      @hash = {}
+      @fields = fields
+      @fields.map!(&:to_s) if @fields.respond_to?(:map)
+    end
+
+    # Adds attribute if attribute name is in <tt>fields</tt> array.
+    #
+    # i.e,
+    #
+    #  JsonApiServer::AttributesBuilder.new(fields)
+    #   .add('name', @object.name)
+    #   .attributes
+    def add(name, value)
+      @hash[name.to_s] = value if add_attr?(name)
+      self
+    end
+
+    # Add multiple attributes.
+    #
+    # i.e,
+    #
+    #  JsonApiServer::AttributesBuilder.new(fields)
+    #   .add_multi(@object, 'name', 'email', 'logins')
+    #   .attributes
+    def add_multi(object, *attrs)
+      attrs.each { |attr| add(attr, object.send(attr)) }
+      self
+    end
+
+    # Adds attribute if attribute name is in <tt>fields</tt> array *and* proc returns true.
+    #
+    # i.e,
+    #
+    #  JsonApiServer::AttributesBuilder.new(fields)
+    #   .add_if('email', @object.email, -> { admin? })
+    #   .attributes
+    def add_if(name, value, proc)
+      @hash[name] = value if add_attr?(name) && proc.call == true
+      self
+    end
+
+    # Returns attributes as a hash.
+    #
+    # i.e.,
+    #  {
+    #    'title' => 'Everyone Poops',
+    #    'body' => 'Taro Gomi',
+    #    'phone' => '123-4567',
+    #    'isbn' => '5555555'
+    #  }
+    def attributes
+      @hash
+    end
+
+    protected
+
+    # Returns true if @fields is not defined. If @fields is defined,
+    # returns true if attribute name is included in the @fields array.
+    def add_attr?(name)
+      @fields.respond_to?(:include?) ? @fields.include?(name.to_s) : true
+    end
+  end
+end

data/lib/json_api_server/base_serializer.rb

@@ -0,0 +1,169 @@
+module JsonApiServer # :nodoc:
+  # === Description
+  #
+  # Base JSON API serializer for this gem. Based on spec document structure:
+  # http://jsonapi.org/format/#document-structure. Classes should inherit and override.
+  # ResourceSerializer and ResourcesSerializer inherit from this class.
+  #
+  # Consists of 4 methods (#links, #data, #included, #meta) which create
+  # the following document structure. The 4 methods should return data
+  # that is serializable to JSON.
+  #
+  #   {
+  #    ":jsonapi": {
+  #      ":version": "1.0"
+  #    },
+  #    ":links": null,
+  #    ":data": null,
+  #    ":included": null,
+  #    ":meta": null
+  #   }
+  #
+  # There is an additional method, #relationship_data, which should be
+  # populated with data for "relationships".
+  #
+  # Example class:
+  #
+  #   class CommentSerializer < JsonApiServer::BaseSerializer
+  #     def initialize(object, **options)
+  #       super(options)
+  #       @object = object
+  #     end
+  #
+  #     def links
+  #       {
+  #         self: File.join(base_url, "/comments/#{@object.id}")
+  #       }
+  #     end
+  #
+  #     def data
+  #       {
+  #         "type": "comments",
+  #         "id": "12",
+  #         "attributes": {
+  #           "comment": @object.comment,
+  #           "created_at": @object.created_at,
+  #           "updated_at": @object.created_at,
+  #         },
+  #         "relationships": {
+  #           "author": {
+  #             "links": {"self": "http://example.com/people/#{@object.author_id}"},
+  #             "data": {"id": @object.author_id, "type": "people"}
+  #           }
+  #         }
+  #       }
+  #     end
+  #   end
+  #
+  # Sometimes only part of document is needed, i.e., when embedding one serializer in another.
+  # <tt>as_json</tt> takes an optional hash argument which determines which parts of the document to return.
+  # These options can also be set in the #as_json_options attribute.
+  #
+  #  serializer.as_json(include: [:data]) # => { data: {...} }
+  #  serializer.as_json(include: [:links]) # => { links: {...} }
+  #  serializer.as_json(include: [:data, :links]) # =>
+  #  # {
+  #  #   links: {...},
+  #  #   data: {...}
+  #  # }
+  #  serializer.as_json(include: [:relationship_data]) # =>
+  #  # {
+  #  #   data: {
+  #  #      # usually links or object_id + type.
+  #  #   }
+  #  # }
+  #
+  # <tt>base_url</tt> -- is JsonApiServer::Configuration#base_url exposed as a protected
+  # method. For creating links.
+  class BaseSerializer
+    include JsonApiServer::Serializer
+    include JsonApiServer::ApiVersion
+
+    # Hash. as_json options. Same options can be passed into #as_json.
+    # Defaults to nil. When not set, all sections are rendered.
+    #
+    # Possible options:
+    #
+    # <tt>:include</tt> (Array) -- Optional. Possible values: :jsonapi, :links, :data,
+    # :included, :meta and :relationship_data. :relationship_data is a special case --
+    # if present in the array, only relationship data is rendered (data section w/o
+    # attributes).
+    #
+    # i.e,
+    #
+    #   # Set attribute
+    #   serializer.as_json_options = { include: [:data] }
+    #   serializer.as_json_options = { include: [:data, :links] }
+    #   serializer.as_json_options = { include: [:relationship_data] }
+    #
+    #   # Or set when calling #as_json
+    #   serializer.as_json(include: [:data])
+    attr_accessor :as_json_options
+
+    def initialize(**options)
+      @as_json_options = options[:as_json_options]
+    end
+
+    # JSON API *links* section. Subclass implements.
+    # Api spec: http://jsonapi.org/format/#document-links
+    def links
+      nil
+    end
+
+    # JSON API *data* section. Subclass implements.
+    # Api spec: http://jsonapi.org/format/#document-structure
+    def data
+      nil
+    end
+
+    # JSON to render with #as_json_option :relationship_data. Subclass implements.
+    # Api spec: http://jsonapi.org/format/#fetching-relationships
+    def relationship_data
+      nil
+    end
+
+    # JSON API *included* section. Sublclass implements.
+    # Api spec: http://jsonapi.org/format/#fetching-includes
+    def included
+      nil
+    end
+
+    # JSON API *meta* section. Sublclass implements.
+    # Api spec: http://jsonapi.org/format/#document-meta
+    def meta
+      nil
+    end
+
+    # Creates the following document structure by default. See #as_json_options for
+    # a description of options. The hash is with indifferent access.
+    #   {
+    #    "jsonapi" => {
+    #      "version" => "1.0"
+    #    },
+    #    "links" => null,
+    #    "data" => null,
+    #    "included" => null,
+    #    "meta" => null
+    #   }
+    def as_json(**options)
+      opts = (options.any? ? options : as_json_options) || {}
+      sections = opts[:include] || %w[jsonapi links data included meta]
+      hash = {}
+
+      if sections.include?(:relationship_data)
+        hash['data'] = relationship_data
+      else
+        sections.each { |s| hash[s] = send(s) if sections.include?(s) }
+      end
+
+      ActiveSupport::HashWithIndifferentAccess.new(hash)
+    end
+
+    protected
+
+    # Configuration base_url.
+    def base_url
+      JsonApiServer.configuration.base_url
+    end
+  end
+end