jsonapi 0.1.1.beta1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: b9684f22cfc478709e3961ccde7d5c528293587c
+  data.tar.gz: 62b48f99bb23746b67fc0e5e42f864d3df8d4116
+SHA512:
+  metadata.gz: f77d8cb69325b8186786e181515c0ce7a30fd6f63fcf5ae22c65ac4e5167c87128a8124e87f63ef4115275f36bd9d79151198c200ec31230917aa2da51b2cd97
+  data.tar.gz: fad6e70f1a1efedea35600adb16784de57c100cfcaab3d18f26ce80c1eb3d06a3cbb22fae5c7cf5da4429ed98a5cbf1576f4812923b64172e13ea566d830a611

data/.gitignore

@@ -0,0 +1,36 @@
+*.gem
+*.rbc
+/.config
+/coverage/
+/InstalledFiles
+/pkg/
+/spec/reports/
+/spec/examples.txt
+/test/tmp/
+/test/version_tmp/
+/tmp/
+
+## Specific to RubyMotion:
+.dat*
+.repl_history
+build/
+
+## Documentation cache and generated files:
+/.yardoc/
+/_yardoc/
+/doc/
+/rdoc/
+
+## Environment normalization:
+/.bundle/
+/vendor/bundle
+/lib/bundler/man/
+
+# for a library or gem, you might want to ignore these files since the code is
+# intended to run in multiple environments; otherwise, check them in:
+# Gemfile.lock
+# .ruby-version
+# .ruby-gemset
+
+# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
+.rvmrc

data/.travis.yml

@@ -0,0 +1,6 @@
+language: ruby
+sudo: false
+rvm:
+  - 2.1
+  - 2.2
+  - 2.3.0

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,48 @@
+PATH
+  remote: .
+  specs:
+    jsonapi (0.1.1.beta1)
+      activesupport (>= 3.0)
+      json (~> 1.8)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activesupport (4.2.6)
+      i18n (~> 0.7)
+      json (~> 1.7, >= 1.7.7)
+      minitest (~> 5.1)
+      thread_safe (~> 0.3, >= 0.3.4)
+      tzinfo (~> 1.1)
+    diff-lcs (1.2.5)
+    i18n (0.7.0)
+    json (1.8.3)
+    minitest (5.8.4)
+    rake (11.1.2)
+    rspec (3.4.0)
+      rspec-core (~> 3.4.0)
+      rspec-expectations (~> 3.4.0)
+      rspec-mocks (~> 3.4.0)
+    rspec-core (3.4.4)
+      rspec-support (~> 3.4.0)
+    rspec-expectations (3.4.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.4.0)
+    rspec-mocks (3.4.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.4.0)
+    rspec-support (3.4.1)
+    thread_safe (0.3.5)
+    tzinfo (1.2.2)
+      thread_safe (~> 0.1)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  jsonapi!
+  rake (>= 0.9)
+  rspec (~> 3.4)
+
+BUNDLED WITH
+   1.11.2

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 Lucas Hosseini
+
+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,141 @@
+# jsonapi
+Ruby gem for parsing/validating [JSON API](http://jsonapi.org) documents.
+
+## Installation
+
+Add the following to your application's Gemfile:
+```ruby
+gem 'jsonapi'
+```
+And then execute:
+```
+$ bundle
+```
+Or install it manually as:
+```
+$ gem install jsonapi
+```
+
+## Usage
+
+First, `require` the gem.
+```ruby
+require 'jsonapi'
+```
+
+Then, parse a JSON API document:
+```ruby
+document = JSONAPI.parse(hash_or_json_string)
+```
+
+or an [include directive](http://jsonapi.org/format/#fetching-includes):
+```ruby
+include_directive = JSONAPI::IncludeDirective.new(include_args)
+```
+
+## Examples
+
+```ruby
+  document = JSONAPI.parse(json_document)
+  # Should the document be invalid, the parse method would fail with an
+  #   InvalidDocument error.
+
+  document.data.to_activerecord_hash
+  # => {
+  #      id: '1',
+  #      title: 'JSON API paints my bikeshed!',
+  #      author_id: '9',
+  #      comment_ids: ['5', '12']
+  #    }
+
+  document.data.links.defined?(:self)
+  # => true
+  document.data.links.self.value
+  # => 'http://example.com/articles/1'
+  document.data.attributes.keys
+  # => ['title']
+  document.data.attributes.defined?(:title)
+  # => true
+  document.data.attributes.title
+  # => 'JSON API paints my bikeshed!'
+  document.data.relationships.keys
+  # => ['author', 'comments']
+  document.data.relationships.defined?(:author)
+  # => true
+  document.data.relationships.author.collection?
+  # => false
+  document.data.relationships.author.data.id
+  # => 9
+  document.data.relationships.author.data.type
+  # => 'people'
+  document.data.relationships.author.links.defined?(:self)
+  # => true
+  document.data.relationships.author.links.self.value
+  # => 'http://example.com/articles/1/relationships/author'
+  document.data.relationships.defined?(:comments)
+  # => true
+  document.data.relationships.comments.collection?
+  # => true
+  document.data.relationships.comments.data.size
+  # => 2
+  document.data.relationships.comments.data[0].id
+  # => 5
+  document.data.relationships.comments.data[0].type
+  # => 'comments'
+  document.data.relationships.comments.links.defined?(:self)
+  # => true
+  document.data.relationships.comments.links.self.value
+  # => 'http://example.com/articles/1/relationships/comments'
+
+  # for the following document_hash
+  document_hash = {
+    'data' =>
+      {
+        'type' => 'articles',
+        'id' => '1',
+        'attributes' => {
+          'title' => 'JSON API paints my bikeshed!'
+        },
+        'links' => {
+          'self' => 'http://example.com/articles/1'
+        },
+        'relationships' => {
+          'author' => {
+            'links' => {
+              'self' => 'http://example.com/articles/1/relationships/author',
+              'related' => 'http://example.com/articles/1/author'
+            },
+            'data' => { 'type' => 'people', 'id' => '9' }
+          },
+          'comments' => {
+            'links' => {
+              'self' => 'http://example.com/articles/1/relationships/comments',
+              'related' => 'http://example.com/articles/1/comments'
+            },
+            'data' => [
+              { 'type' => 'comments', 'id' => '5' },
+              { 'type' => 'comments', 'id' => '12' }
+            ]
+          }
+        }
+      }
+    }
+```
+
+## Contributing
+
+1. Fork the [official repository](https://github.com/beauby/jsonapi_parser/tree/master).
+2. Make your changes in a topic branch.
+3. Send a pull request.
+
+Notes:
+
+* Contributions without tests won't be accepted.
+* Please don't update the Gem version.
+
+## License
+
+jsonapi_parser is Copyright © 2016 Lucas Hosseini.
+
+It is free software, and may be redistributed under the terms specified in the
+[LICENSE](LICENSE) file.

data/Rakefile

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

data/jsonapi_parser.gemspec

@@ -0,0 +1,25 @@
+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'
+  spec.version       = JSONAPI::VERSION
+  spec.authors       = ['Lucas Hosseini']
+  spec.email         = ['lucas.hosseini@gmail.com']
+  spec.summary       = 'Parse and validate JSON API documents'
+  spec.description   = 'Tools for handling JSON API documents'
+  spec.homepage      = 'https://github.com/beauby/jsonapi'
+  spec.license       = 'MIT'
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(spec)/})
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'json', '~>1.8'
+  spec.add_dependency 'activesupport', '>=3.0'
+
+  spec.add_development_dependency 'rake', '>=0.9'
+  spec.add_development_dependency 'rspec', '~>3.4'
+end

data/lib/jsonapi/attributes.rb

@@ -0,0 +1,41 @@
+module JSONAPI
+  # c.f. http://jsonapi.org/format/#document-resource-object-attributes
+  class Attributes
+    include Enumerable
+
+    def initialize(attributes_hash, options = {})
+      fail InvalidDocument,
+           "the value of 'attributes' MUST be an object" unless
+        attributes_hash.is_a?(Hash)
+
+      @hash = attributes_hash
+      @attributes = {}
+      attributes_hash.each do |attr_name, attr_val|
+        @attributes[attr_name.to_s] = attr_val
+        define_singleton_method(attr_name) do
+          @attributes[attr_name.to_s]
+        end
+      end
+    end
+
+    def to_hash
+      @hash
+    end
+
+    def each(&block)
+      @attributes.each(&block)
+    end
+
+    def [](attr_name)
+      @attributes[attr_name.to_s]
+    end
+
+    def defined?(attr_name)
+      @attributes.key?(attr_name.to_s)
+    end
+
+    def keys
+      @attributes.keys
+    end
+  end
+end

data/lib/jsonapi/document.rb

@@ -0,0 +1,126 @@
+module JSONAPI
+  # c.f. http://jsonapi.org/format/#document-top-level
+  class Document
+    attr_reader :data, :meta, :errors, :json_api, :links, :included
+
+    def initialize(document_hash, options = {})
+      @hash = document_hash
+      @options = options
+      @data_defined = document_hash.key?('data')
+      @data = parse_data(document_hash['data']) if @data_defined
+      @meta_defined = document_hash.key?('meta')
+      @meta = parse_meta(document_hash['meta']) if @meta_defined
+      @errors_defined = document_hash.key?('errors')
+      @errors = parse_errors(document_hash['errors']) if @errors_defined
+      @jsonapi_defined = document_hash.key?('jsonapi')
+      @jsonapi = JsonApi.new(document_hash['jsonapi'], @options) if
+        @jsonapi_defined
+      @links_hash = document_hash['links'] || {}
+      @links = Links.new(@links_hash, @options)
+      @included_defined = document_hash.key?('included')
+      @included = parse_included(document_hash['included']) if
+        @included_defined
+
+      validate!
+    end
+
+    def to_hash
+      @hash
+    end
+
+    def collection?
+      @data.is_a?(Array)
+    end
+
+    private
+
+    def validate!
+      case
+      when !@data_defined && !@meta_defined && !@errors_defined
+        fail InvalidDocument,
+             "a document MUST contain at least one of 'data', 'meta', or" \
+             " or 'errors' at top-level"
+      when @data_defined && @errors_defined
+        fail InvalidDocument,
+             "'data' and 'errors' MUST NOT coexist in the same document"
+      when !@data_defined && @included_defined
+        fail InvalidDocument, "'included' MUST NOT be present unless 'data' is"
+      when @options[:verify_duplicates] && duplicates?
+        fail InvalidDocument,
+             "resources MUST NOT appear both in 'data' and 'included'"
+      when @options[:verify_linkage] && !full_linkage?
+        fail InvalidDocument,
+             "resources in 'included' MUST respect full-linkage"
+      end
+    end
+
+    def duplicates?
+      resources = Set.new
+
+      (Array(data) + Array(included)).each do |resource|
+        return true unless resources.add?([resource.type, resource.id])
+      end
+
+      false
+    end
+
+    def full_linkage?
+      return true unless @included
+
+      reachable = Set.new
+      # NOTE(lucas): Does Array() already dup?
+      queue = Array(data).dup
+      included_resources = Hash[included.map { |r| [[r.type, r.id], r] }]
+      queue.each { |resource| reachable << [resource.type, resource.id] }
+
+      traverse = lambda do |rel|
+        ri = [rel.type, rel.id]
+        return unless included_resources[ri]
+        return unless reachable.add?(ri)
+        queue << included_resources[ri]
+      end
+
+      until queue.empty?
+        resource = queue.pop
+        resource.relationships.each do |_, rel|
+          Array(rel.data).map(&traverse)
+        end
+      end
+
+      included_resources.keys.all? { |ri| reachable.include?(ri) }
+    end
+
+    def parse_data(data_hash)
+      collection = data_hash.is_a?(Array)
+      if collection
+        data_hash.map { |h| Resource.new(h, @options.merge(id_optional: true)) }
+      elsif data_hash.nil?
+        nil
+      else
+        Resource.new(data_hash, @options.merge(id_optional: true))
+      end
+    end
+
+    def parse_meta(meta_hash)
+      fail InvalidDocument, "the value of 'meta' MUST be an object" unless
+        meta_hash.is_a?(Hash)
+      meta_hash
+    end
+
+    def parse_included(included_hash)
+      fail InvalidDocument,
+           "the value of 'included' MUST be an array of resource objects" unless
+        included_hash.is_a?(Array)
+
+      included_hash.map { |h| Resource.new(h, @options) }
+    end
+
+    def parse_errors(errors_hash)
+      fail InvalidDocument,
+           "the value of 'errors' MUST be an array of error objects" unless
+        errors_hash.is_a?(Array)
+
+      errors_hash.map { |h| Error.new(h, @options) }
+    end
+  end
+end

data/lib/jsonapi/error.rb

@@ -0,0 +1,27 @@
+module JSONAPI
+  # c.f. http://jsonapi.org/format/#error-objects
+  class Error
+    attr_reader :id, :links, :status, :code, :title, :detail, :source, :meta
+
+    def initialize(error_hash, options = {})
+      fail InvalidDocument,
+           "the value of 'errors' MUST be an array of error objects" unless
+        error_hash.is_a?(Hash)
+
+      @hash = error_hash
+      @id = error_hash['id'] if error_hash.key?('id')
+      links_hash = error_hash['links'] || {}
+      @links = Links.new(links_hash, options)
+      @status = error_hash['status'] if error_hash.key?('status')
+      @code = error_hash['code'] if error_hash.key?('code')
+      @title = error_hash['title'] if error_hash.key?('title')
+      @detail = error_hash['detail'] if error_hash.key?('detail')
+      @source = error_hash['source'] if error_hash.key?('source')
+      @meta = error_hash['meta'] if error_hash.key?('meta')
+    end
+
+    def to_hash
+      @hash
+    end
+  end
+end

data/lib/jsonapi/exceptions.rb

@@ -0,0 +1,4 @@
+module JSONAPI
+  class InvalidDocument < StandardError
+  end
+end

data/lib/jsonapi/include_directive/parser.rb

@@ -0,0 +1,57 @@
+require 'active_support/core_ext/hash/deep_merge'
+
+module JSONAPI
+  class IncludeDirective
+    # Utilities to create an IncludeDirective hash from various types of
+    # inputs.
+    module Parser
+      module_function
+
+      # @api private
+      def parse_include_args(include_args)
+        case include_args
+        when Symbol
+          { include_args => {} }
+        when Hash
+          parse_hash(include_args)
+        when Array
+          parse_array(include_args)
+        when String
+          parse_string(include_args)
+        else
+          {}
+        end
+      end
+
+      # @api private
+      def parse_string(include_string)
+        include_string.split(',')
+          .map(&:strip)
+          .each_with_object({}) do |path, hash|
+          hash.deep_merge!(parse_path_string(path))
+        end
+      end
+
+      # @api private
+      def parse_path_string(include_path)
+        include_path.split('.')
+          .reverse
+          .reduce({}) { |a, e| { e.to_sym => a } }
+      end
+
+      # @api private
+      def parse_hash(include_hash)
+        include_hash.each_with_object({}) do |(key, value), hash|
+          hash[key.to_sym] = parse_include_args(value)
+        end
+      end
+
+      # @api private
+      def parse_array(include_array)
+        include_array.each_with_object({}) do |x, hash|
+          hash.deep_merge!(parse_include_args(x))
+        end
+      end
+    end
+  end
+end

data/lib/jsonapi/include_directive.rb

@@ -0,0 +1,67 @@
+require 'jsonapi/include_directive/parser'
+
+module JSONAPI
+  # Represent a recursive set of include directives
+  # (c.f. http://jsonapi.org/format/#fetching-includes)
+  #
+  # Addition to the spec: two wildcards, namely '*' and '**'.
+  # The former stands for any one level of relationship, and the latter stands
+  # for any number of levels of relationships.
+  # @example 'posts.*' # => Include related posts, and all the included posts'
+  #   related resources.
+  # @example 'posts.**' # => Include related posts, and all the included
+  #   posts' related resources, and their related resources, recursively.
+  class IncludeDirective
+    # @param include_args (see Parser.include_hash_from_include_args)
+    def initialize(include_args, options = {})
+      include_hash = Parser.parse_include_args(include_args)
+      @hash = include_hash.each_with_object({}) do |(key, value), hash|
+        hash[key] = self.class.new(value, options)
+      end
+      @options = options
+    end
+
+    # @param key [Symbol, String]
+    def key?(key)
+      @hash.key?(key.to_sym) ||
+        (@options[:allow_wildcard] && (@hash.key?(:*) || @hash.key?(:**)))
+    end
+
+    # @param key [Symbol, String]
+    # @return [IncludeDirective, nil]
+    def [](key)
+      case
+      when @hash.key?(key.to_sym)
+        @hash[key.to_sym]
+      when @options[:allow_wildcard] && @hash.key?(:**)
+        self.class.new({ :** => {} }, @options)
+      when @options[:allow_wildcard] && @hash.key?(:*)
+        @hash[:*]
+      end
+    end
+
+    # @return [Hash{Symbol => Hash}]
+    def to_hash
+      @hash.each_with_object({}) do |(key, value), hash|
+        hash[key] = value.to_hash
+      end
+    end
+
+    # @return [String]
+    def to_string
+      string_array = @hash.map do |(key, value)|
+        string_value = value.to_string
+        if string_value == ''
+          key.to_s
+        else
+          string_value
+            .split(',')
+            .map { |x| key.to_s + '.' + x }
+            .join(',')
+        end
+      end
+
+      string_array.join(',')
+    end
+  end
+end

data/lib/jsonapi/jsonapi.rb

@@ -0,0 +1,19 @@
+module JSONAPI
+  # c.f. http://jsonapi.org/format/#document-jsonapi-object
+  class JsonApi
+    attr_reader :version, :meta
+
+    def initialize(jsonapi_hash, options = {})
+      fail InvalidDocument, "the value of 'jsonapi' MUST be an object" unless
+        jsonapi_hash.is_a?(Hash)
+
+      @hash = jsonapi_hash
+      @version = jsonapi_hash['version'] if jsonapi_hash.key?('meta')
+      @meta = jsonapi_hash['meta'] if jsonapi_hash.key?('meta')
+    end
+
+    def to_hash
+      @hash
+    end
+  end
+end

data/lib/jsonapi/link.rb

@@ -0,0 +1,41 @@
+module JSONAPI
+  # c.f. http://jsonapi.org/format/#document-links
+  class Link
+    attr_reader :value, :href, :meta
+
+    def initialize(link_hash, options = {})
+      @hash = link_hash
+
+      validate!(link_hash)
+      @value = link_hash
+      return unless link_hash.is_a?(Hash)
+
+      @href = link_hash['href']
+      @meta = link_hash['meta']
+    end
+
+    def to_hash
+      @hash
+    end
+
+    private
+
+    def validate!(link_hash)
+      case
+      when !link_hash.is_a?(String) && !link_hash.is_a?(Hash)
+        fail InvalidDocument,
+             "a 'link' object MUST be either a string or an object"
+      when link_hash.is_a?(Hash) && (!link_hash.key?('href') ||
+                                     !link_hash['href'].is_a?(String))
+        fail InvalidDocument,
+             "a 'link' object MUST be either a string or an object containing" \
+             " an 'href' string"
+      when link_hash.is_a?(Hash) && (!link_hash.key?('meta') ||
+                                     !link_hash['meta'].is_a?(Hash))
+        fail InvalidDocument,
+             "a 'link' object MUST be either a string or an object containing" \
+             " an 'meta' object"
+      end
+    end
+  end
+end