jsonapi 0.1.1.beta1

data/lib/jsonapi/links.rb

@@ -0,0 +1,34 @@
+module JSONAPI
+  # c.f. http://jsonapi.org/format/#document-links
+  class Links
+    def initialize(links_hash, options = {})
+      fail InvalidDocument, "the value of 'links' MUST be an object" unless
+        links_hash.is_a?(Hash)
+
+      @hash = links_hash
+      @links = {}
+      links_hash.each do |link_name, link_val|
+        @links[link_name.to_s] = Link.new(link_val, options)
+        define_singleton_method(link_name) do
+          @links[link_name.to_s]
+        end
+      end
+    end
+
+    def to_hash
+      @hash
+    end
+
+    def defined?(link_name)
+      @links.key?(link_name.to_s)
+    end
+
+    def [](link_name)
+      @links[link_name.to_s]
+    end
+
+    def keys
+      @links.keys
+    end
+  end
+end

data/lib/jsonapi/parse.rb

@@ -0,0 +1,18 @@
+require 'json'
+
+module JSONAPI
+  module_function
+
+  # Parse a JSON API document.
+  #
+  # @param document [Hash, String] the JSON API document.
+  # @param options [Hash] options
+  # @option options [Boolean] :id_optional (false) whether the resource
+  #   objects in the primary data must have an id
+  # @return [JSON::API::Document]
+  def parse(document, options = {})
+    hash = document.is_a?(Hash) ? document : JSON.parse(document)
+
+    Document.new(hash, options)
+  end
+end

data/lib/jsonapi/relationship.rb

@@ -0,0 +1,57 @@
+module JSONAPI
+  # c.f. http://jsonapi.org/format/#document-resource-object-relationships
+  class Relationship
+    attr_reader :data, :links, :meta
+
+    def initialize(relationship_hash, options = {})
+      @hash = relationship_hash
+      @options = options
+      @links_defined = relationship_hash.key?('links')
+      @data_defined = relationship_hash.key?('data')
+      @meta_defined = relationship_hash.key?('meta')
+      links_hash = relationship_hash['links'] || {}
+      @links = Links.new(links_hash, @options)
+      @data = parse_linkage(relationship_hash['data']) if
+        @data_defined
+      @meta = relationship_hash['meta'] if @meta_defined
+
+      validate!
+    end
+
+    def to_hash
+      @hash
+    end
+
+    def collection?
+      @data.is_a?(Array)
+    end
+
+    private
+
+    def validate!
+      case
+      when !@links_defined && !@data_defined && !@meta_defined
+        fail InvalidDocument,
+             "a relationship object MUST contain at least one of 'links'," \
+             " 'data', or 'meta'"
+      when @links_defined &&
+           !@links.defined?(:self) &&
+           !@links.defined?(:related)
+        fail InvalidDocument,
+             "the 'links' object of a relationship object MUST contain at" \
+             " least one of 'self' or 'related'"
+      end
+    end
+
+    def parse_linkage(linkage_hash)
+      collection = linkage_hash.is_a?(Array)
+      if collection
+        linkage_hash.map { |h| ResourceIdentifier.new(h, @options) }
+      elsif linkage_hash.nil?
+        nil
+      else
+        ResourceIdentifier.new(linkage_hash, @options)
+      end
+    end
+  end
+end

data/lib/jsonapi/relationships.rb

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

data/lib/jsonapi/resource/active_record.rb

@@ -0,0 +1,151 @@
+require 'active_support/core_ext/string/inflections'
+
+module JSONAPI
+  class Resource
+    # Transform the resource object into a hash ready for ActiveRecord's
+    # new/create/update.
+    #
+    # @example
+    #   payload = {
+    #     'data' => {
+    #       'type' => 'articles',
+    #       'id' => '1',
+    #       'attributes' => {
+    #         'title' => 'JSON API paints my bikeshed!',
+    #         'rating' => '5 stars'
+    #       },
+    #       'relationships' => {
+    #         'author' => {
+    #           'data' => { 'type' => 'people', 'id' => '9' }
+    #         },
+    #         'referree' => {
+    #           'data' => nil
+    #         },
+    #         'publishing-journal' => {
+    #           'data' => nil
+    #         },
+    #         'comments' => {
+    #           'data' => [
+    #             { 'type' => 'comments', 'id' => '5' },
+    #             { 'type' => 'comments', 'id' => '12' }
+    #           ]
+    #         }
+    #       }
+    #     }
+    #   }
+    #   document = JSON::API.parse(payload)
+    #   options = {
+    #     attributes: {
+    #       except: [:rating]
+    #     },
+    #     relationships: {
+    #       only: [:author, :'publishing-journal', :comments],
+    #       polymorphic: [:author]
+    #     },
+    #     key_formatter: ->(x) { x.underscore }
+    #   }
+    #   document.data.to_activerecord_hash(options)
+    #   # => {
+    #          id: '1',
+    #          title: 'JSON API paints my bikeshed!',
+    #          author_id: '9',
+    #          author_type: 'people',
+    #          publishing_journal_id: nil,
+    #          comment_ids: ['5', '12']
+    #        }
+    #
+    # @param options [Hash]
+    #   * :attributes (Hash)
+    #     * :only (Array<Symbol,String>)
+    #     * :except (Array<Symbol,String>)
+    #   * :relationships (Hash)
+    #     * :only (Array<Symbol,String>)
+    #     * :except (Array<Symbol,String>)
+    #     * :polymorphic (Array<Symbol,String>)
+    #   * :key_formatter (lambda)
+    # @return [Hash]
+    def to_activerecord_hash(options = {})
+      options[:attributes] ||= {}
+      options[:relationships] ||= {}
+      hash = {}
+      hash[:id] = id unless id.nil?
+      hash.merge!(attributes_for_activerecord_hash(options))
+      hash.merge!(relationships_for_activerecord_hash(options))
+
+      hash
+    end
+
+    private
+
+    def attributes_for_activerecord_hash(options)
+      attributes_hashes =
+        filter_keys(attributes.keys, options[:attributes]).map do |key|
+        attribute_for_activerecord_hash(key, options[:key_formatter])
+      end
+
+      attributes_hashes.reduce({}, :merge)
+    end
+
+    def attribute_for_activerecord_hash(key, key_formatter)
+      { format_key(key, key_formatter).to_sym => attributes[key] }
+    end
+
+    def relationships_for_activerecord_hash(options)
+      relationship_hashes =
+        filter_keys(relationships.keys, options[:relationships]).map do |key|
+        polymorphic = (options[:relationships][:polymorphic] || [])
+                      .include?(key.to_sym)
+        relationship_for_activerecord_hash(key,
+                                           options[:key_formatter],
+                                           polymorphic)
+      end
+
+      relationship_hashes.reduce({}, :merge)
+    end
+
+    def relationship_for_activerecord_hash(rel_name,
+                                           key_formatter,
+                                           polymorphic)
+      rel = relationships[rel_name]
+      key = format_key(rel_name, key_formatter)
+
+      if rel.collection?
+        to_many_relationship_for_activerecord_hash(key, rel)
+      else
+        to_one_relationship_for_activerecord_hash(key, rel, polymorphic)
+      end
+    end
+
+    def to_many_relationship_for_activerecord_hash(key, rel)
+      { "#{key.singularize}_ids".to_sym => rel.data.map(&:id) }
+    end
+
+    def to_one_relationship_for_activerecord_hash(key, rel, polymorphic)
+      value = rel.data ? rel.data.id : nil
+      hash = { "#{key}_id".to_sym => value }
+      if polymorphic && !rel.data.nil?
+        hash["#{key}_type".to_sym] = rel.data.type.singularize.capitalize
+      end
+
+      hash
+    end
+
+    def format_key(key, key_formatter)
+      if key_formatter
+        key_formatter.call(key)
+      else
+        key
+      end
+    end
+
+    def filter_keys(keys, filter)
+      if filter[:only]
+        keys & filter[:only].map(&:to_s)
+      elsif filter[:except]
+        keys - filter[:except].map(&:to_s)
+      else
+        keys
+      end
+    end
+  end
+end

data/lib/jsonapi/resource.rb

@@ -0,0 +1,48 @@
+require 'jsonapi/resource/active_record'
+
+module JSONAPI
+  # c.f. http://jsonapi.org/format/#document-resource-objects
+  class Resource
+    attr_reader :id, :type, :attributes, :relationships, :links, :meta
+
+    def initialize(resource_hash, options = {})
+      @hash = resource_hash
+      @options = options.dup
+      @id_optional = @options.delete(:id_optional)
+      validate!(resource_hash)
+      @id = resource_hash['id']
+      @type = resource_hash['type']
+      @attributes_hash = resource_hash['attributes'] || {}
+      @attributes = Attributes.new(@attributes_hash, @options)
+      @relationships_hash = resource_hash['relationships'] || {}
+      @relationships = Relationships.new(@relationships_hash, @options)
+      @links_hash = resource_hash['links'] || {}
+      @links = Links.new(@links_hash, @options)
+      @meta = resource_hash['meta'] if resource_hash.key?('meta')
+    end
+
+    def to_hash
+      @hash
+    end
+
+    private
+
+    def validate!(resource_hash)
+      case
+      when !@id_optional && !resource_hash.key?('id')
+        # We might want to take care of
+        # > Exception: The id member is not required when the resource object
+        # > originates at the client and represents a new resource to be created
+        # > on the server.
+        # in the future.
+        fail InvalidDocument, "a resource object MUST contain an 'id'"
+      when !@id_optional && !resource_hash['id'].is_a?(String)
+        fail InvalidDocument, "the value of 'id' MUST be a string"
+      when !resource_hash.key?('type')
+        fail InvalidDocument, "a resource object MUST contain a 'type'"
+      when !resource_hash['type'].is_a?(String)
+        fail InvalidDocument, "the value of 'type' MUST be a string"
+      end
+    end
+  end
+end

data/lib/jsonapi/resource_identifier.rb

@@ -0,0 +1,36 @@
+module JSONAPI
+  # c.f. http://jsonapi.org/format/#document-resource-identifier-objects
+  class ResourceIdentifier
+    attr_reader :id, :type
+
+    def initialize(resource_identifier_hash, options = {})
+      @hash = resource_identifier_hash
+
+      validate!(resource_identifier_hash)
+
+      @id = resource_identifier_hash['id']
+      @type = resource_identifier_hash['type']
+    end
+
+    def to_hash
+      @hash
+    end
+
+    private
+
+    def validate!(resource_identifier_hash)
+      case
+      when !resource_identifier_hash.key?('id')
+        fail InvalidDocument,
+             "a resource identifier object MUST contain an 'id'"
+      when !resource_identifier_hash['id'].is_a?(String)
+        fail InvalidDocument, "the value of 'id' MUST be a string"
+      when !resource_identifier_hash.key?('type')
+        fail InvalidDocument,
+             "a resource identifier object MUST contain a 'type'"
+      when !resource_identifier_hash['type'].is_a?(String)
+        fail InvalidDocument, "the value of 'type' MUST be a string"
+      end
+    end
+  end
+end

data/lib/jsonapi/version.rb

@@ -0,0 +1,3 @@
+module JSONAPI
+  VERSION = '0.1.1.beta1'.freeze
+end

data/lib/jsonapi.rb

@@ -0,0 +1,18 @@
+require 'jsonapi/exceptions'
+require 'jsonapi/version'
+
+require 'jsonapi/attributes'
+require 'jsonapi/document'
+require 'jsonapi/error'
+require 'jsonapi/jsonapi'
+require 'jsonapi/link'
+require 'jsonapi/links'
+require 'jsonapi/relationship'
+require 'jsonapi/relationships'
+require 'jsonapi/resource'
+require 'jsonapi/resource_identifier'
+
+require 'jsonapi/parse'
+
+module JSONAPI
+end

data/spec/duplicates_spec.rb

@@ -0,0 +1,95 @@
+require 'jsonapi'
+
+describe JSONAPI, '#parse' do
+  it 'succeeds when there are no duplicates' do
+    payload = {
+      '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' }
+            },
+            'journal' => {
+              'data' => nil
+            },
+            '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' }
+              ]
+            }
+          }
+        }]
+    }
+
+    JSONAPI.parse(payload, verify_duplicates: true)
+  end
+
+  it 'fails when there are duplicates within primary data' do
+    payload = {
+      'data' => [
+        {
+          'type' => 'articles',
+          'id' => '1'
+        }, {
+          'type' => 'articles',
+          'id' => '1'
+        }]
+    }
+
+    expect { JSONAPI.parse(payload, verify_duplicates: true) }
+      .to raise_error(JSONAPI::InvalidDocument)
+  end
+
+  it 'fails when there are duplicates within included' do
+    payload = {
+      'data' => nil,
+      'included' => [
+        {
+          'type' => 'articles',
+          'id' => '1'
+        }, {
+          'type' => 'articles',
+          'id' => '1'
+        }]
+    }
+
+    expect { JSONAPI.parse(payload, verify_duplicates: true) }
+      .to raise_error(JSONAPI::InvalidDocument)
+  end
+
+  it 'fails when there are duplicates within primary data' do
+    payload = {
+      'data' => [
+        {
+          'type' => 'articles',
+          'id' => '1'
+        }
+      ],
+      'included' => [
+        {
+          'type' => 'articles',
+          'id' => '1'
+        }]
+    }
+
+    expect { JSONAPI.parse(payload, verify_duplicates: true) }
+      .to raise_error(JSONAPI::InvalidDocument)
+  end
+end

data/spec/full_linkage_spec.rb

@@ -0,0 +1,161 @@
+require 'jsonapi'
+
+describe JSONAPI, '#parse' do
+  it 'succeeds when no included property is provided' do
+    payload = {
+      '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' }
+            },
+            'journal' => {
+              'data' => nil
+            },
+            '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' }
+              ]
+            }
+          }
+        }]
+    }
+
+    JSONAPI.parse(payload, verify_linkage: true)
+  end
+
+  it 'succeeds when full linkage is respected' do
+    payload = {
+      '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' }
+            },
+            'journal' => {
+              'data' => nil
+            },
+            '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' }
+              ]
+            }
+          }
+        }],
+      'included' => [
+        {
+          'type' => 'comments',
+          'id' => '5'
+        }, {
+          'type' => 'comments',
+          'id' => '12'
+        }, {
+          'type' => 'comments',
+          'id' => '13'
+        }, {
+          'type' => 'people',
+          'id' => '9',
+          'relationships' => {
+            'comments' => {
+              'data' => [
+                {
+                  'type' => 'comments',
+                  'id' => '13'
+                }
+              ]
+            }
+          }
+        }
+      ]
+    }
+
+    JSONAPI.parse(payload, verify_linkage: true)
+  end
+
+  it 'fails when full linkage is not respected' do
+    payload = {
+      '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' }
+            },
+            'journal' => {
+              'data' => nil
+            },
+            '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' }
+              ]
+            }
+          }
+        }],
+      'included' => [
+        {
+          'type' => 'comments',
+          'id' => '5'
+        }, {
+          'type' => 'comments',
+          'id' => '12'
+        }, {
+          'type' => 'comments',
+          'id' => '13'
+        }
+      ]
+    }
+
+    expect { JSONAPI.parse(payload, verify_linkage: true) }
+      .to raise_error(JSONAPI::InvalidDocument)
+  end
+end