api_navigator 0.0.1

data/lib/api_navigator/link_collection.rb

@@ -0,0 +1,63 @@
+module ApiNavigator
+  # Public: A wrapper class to easily acces the links in a  Resource.
+  #
+  # Examples
+  #
+  #   resource.links['author']
+  #   resource.links.author
+  #
+  class LinkCollection < CollectionHash
+    attr_reader :_curies
+
+    # Public: Initializes a LinkCollection.
+    #
+    # collection  - The Hash with the links.
+    # curies      - The Hash with link curies.
+    # entry_point - The EntryPoint object to inject the configuration.
+    def initialize(collection, curies, entry_point)
+      raise "Invalid response for LinkCollection. The response was: #{collection.inspect}" if collection && !collection.respond_to?(:collect)
+
+      @_curies = (curies || {}).reduce({}) do |hash, curie_hash|
+        curie = build_curie(curie_hash, entry_point)
+        hash.update(curie.name => curie)
+      end
+
+      @collection = (collection || {}).reduce({}) do |hash, (name, link)|
+        hash.update(name => build_link(name, link, @_curies, entry_point))
+      end
+    end
+
+    private
+
+    # Internal: Creates links from the response hash.
+    #
+    # name          - A String to identify the link's name.
+    # link_or_links - A Hash or an Array of hashes with the links to build.
+    # curies        - An Array of Curies for templated links.
+    # entry_point   - The EntryPoint object to inject the configuration.
+    #
+    # Returns a Link or an Array of Links when given an Array.
+    def build_link(name, link_or_links, curies, entry_point)
+      return unless link_or_links
+
+      if link_or_links.respond_to?(:to_ary)
+        link_or_links.map do |link|
+          build_link(name, link, curies, entry_point)
+        end
+      else
+        Link.new(name, link_or_links, entry_point)
+      end
+    end
+
+    # Internal: Creates a curie from the response hash.
+    #
+    # curie_hash - A Hash with the curie.
+    # entry_point - The EntryPoint object to inject the configuration.
+    #
+    # Returns a Link or an array of Links when given an Array.
+    def build_curie(curie_hash, entry_point)
+      Curie.new(curie_hash, entry_point)
+    end
+
+  end
+end

data/lib/api_navigator/resource.rb

@@ -0,0 +1,130 @@
+require 'forwardable'
+require 'pry'
+
+module ApiNavigator
+  # Public: Exception that is raised when passing in invalid representation data
+  # for the resource.
+  class InvalidRepresentationError < ArgumentError
+    attr_reader :representation
+
+    def initialize(error_description, representation)
+      super(error_description)
+      @representation = representation
+    end
+  end
+
+  # Public: Represents a resource from your API. Its responsability is to
+  # ease the way you access its  attributes, links and embedded resources.
+  class Resource
+    extend Forwardable
+
+    # Public: Returns the links of the Resource as a LinkCollection.
+    attr_reader :_links
+
+    # Public: Returns the response object for the HTTP request that created this
+    # resource, if one exists.
+    attr_reader :_response
+
+    # Public: Delegate all HTTP methods (get, post, put, delete, options and
+    # head) to its self link.
+    def_delegators :_self_link, :_get, :_post, :_put, :_delete, :_options, :_head
+
+    def self.from_representation(representation, entry_point, response = nil)
+      case (representation || {}).fetch('data', "_no_data")
+        when Hash
+          Resources::MemberResource.from_representation(representation, entry_point, response)
+        when Array
+          Resources::CollectionResource.new(representation, entry_point, response)
+        when "_no_data"
+          new(representation, entry_point, response)
+        else
+          raise InvalidRepresentationError.new("Representation has not valid data element - must be Hash or List", representation)
+      end
+    end
+
+    # Public: Initializes a Resource.
+    #
+    # representation - The hash with the HAL representation of the Resource.
+    # entry_point    - The EntryPoint object to inject the configutation.
+    def initialize(representation, entry_point, response = nil)
+      representation = validate(representation)
+      links          = representation['_links'] || {}
+      @_links        = LinkCollection.new(links, links['curies'], entry_point)
+      @_entry_point  = entry_point
+      @_response     = response
+    end
+
+    def inspect
+      "#<#{self.class.name} self_link:#{_self_link.inspect} attributes:#{@_attributes.inspect}  collection:#{@_collection.inspect}>"
+    end
+
+    def _success?
+      _response && _response.success?
+    end
+
+    def _status
+      _response && _response.status
+    end
+
+    def [](name)
+      send(name) if respond_to?(name)
+    end
+
+    def fetch(key, *args)
+      return self[key] if respond_to?(key)
+
+      if args.any?
+        args.first
+      elsif block_given?
+        yield key
+      else
+        raise KeyError
+      end
+    end
+
+    private
+
+    # Internal: Ensures the received representation is a valid Hash-lookalike.
+    def validate(representation)
+      return {} unless representation
+
+      if representation.respond_to?(:to_hash)
+        representation.to_hash.dup
+      else
+        raise InvalidRepresentationError.new(
+          "Invalid representation for resource (got #{representation.class}, expected Hash). " \
+          "Is your web server returning JSON HAL data with a 'Content-Type: application/hal+json' header?",
+          representation
+        )
+      end
+    end
+
+    # Internal: Returns the self Link of the Resource. Used to handle the HTTP
+    # methods.
+    def _self_link
+      @_links['self']
+    end
+
+    # Internal: Delegate the method to various elements of the resource.
+    #
+    # This allows `api.posts` instead of `api.links.posts.resource`
+    # as well as api.posts(id: 1) assuming posts is a link.
+    def method_missing(method, *args, &block)
+      # if _links.respond_to?(method, include_private)
+        if args.any? && args.first.is_a?(Hash)
+          return _links.send(method, [], &block)._expand(*args)
+        else
+          return _links.send(method, *args, &block)
+        end
+      # end
+
+      super
+    end
+
+    # Internal: Accessory method to allow the resource respond to
+    # methods that will hit method_missing.
+    def respond_to_missing?(method, include_private = false)
+      _links.respond_to?(method, include_private)
+    end
+  end
+end

data/lib/api_navigator/resources/collection_resource.rb

@@ -0,0 +1,41 @@
+module ApiNavigator
+  module Resources
+    class CollectionResource < Resource
+
+      # Public: Returns the embedded resource of the Resource as a
+      # ResourceCollection.
+      attr_reader :_collection
+
+      # Public: Initializes a Resource.
+      #
+      # representation - The hash with the HAL representation of the Resource.
+      # entry_point    - The EntryPoint object to inject the configutation.
+      def initialize(representation, entry_point, response = nil)
+        super
+        
+        collection_data = representation.fetch('data')
+        @_collection    = collection_data.map do |resource| Resources::MemberResource.from_representation(resource, entry_point) end
+      end
+
+      # Internal: Delegate the method to various elements of the resource.
+      #
+      # This allows `api.posts` instead of `api.links.posts.resource`
+      # as well as api.posts(id: 1) assuming posts is a link.
+      def method_missing(method, *args, &block)
+        begin
+          @_collection.send(method, *args, &block)
+        rescue NoMethodError
+          super
+        end
+      end
+
+      # Internal: Accessory method to allow the resource respond to
+      # methods that will hit method_missing.
+      def respond_to_missing?(method, include_private = false)
+        @_collection.respond_to?(method, include_private) ||
+          super
+      end
+
+    end # class CollectionResource < Resource
+  end
+end

data/lib/api_navigator/resources/member_resource.rb

@@ -0,0 +1,63 @@
+module ApiNavigator
+  module Resources
+    class MemberResource < Resource
+
+      # Public: Returns the attributes of the Resource as Attributes.
+      attr_reader :_attributes
+
+      class << self
+        def from_representation(representation, entry_point, response = nil)
+          client_identifier = entry_point.client_identifier
+          identifier        = representation.fetch('_meta',{})['type']
+          resource_class    = ApiNavigator.resource_class(identifier, client_identifier: client_identifier)
+
+          resource_class.new(representation, entry_point, response)
+        end
+      end
+
+      # Public: Initializes a Resource.
+      #
+      # representation - The hash with the HAL representation of the Resource.
+      # entry_point    - The EntryPoint object to inject the configutation.
+      def initialize(representation, entry_point, response = nil)
+        super
+
+        @_attributes = Attributes.new(representation.fetch('data'))
+      end
+
+      # Internal: Delegate the method to various elements of the resource.
+      #
+      # This allows `api.posts` instead of `api.links.posts.resource`
+      # as well as api.posts(id: 1) assuming posts is a link.
+      def method_missing(method, *args, &block)
+        if @_attributes.include?(method.to_s)
+          result = @_attributes[method.to_s]
+
+          if representation = resource_representation(result)
+            Resource.from_representation(representation, @_entry_point)
+          else
+            result
+          end
+        else
+          super
+        end
+      end
+
+      # Internal: Accessory method to allow the resource respond to
+      # methods that will hit method_missing.
+      def respond_to_missing?(method, include_private = false)
+        @_attributes.include?(method.to_s) ||
+          super
+      end
+
+      def resource_representation(data)
+        return data if (data.kind_of?(Hash) && !data["data"].nil?)
+
+        return { 'data' => data } if (data.kind_of?(Array) && resource_representation(data.first))
+
+        nil
+      end
+
+    end # class MemberResource < Resource
+  end
+end

data/lib/api_navigator/version.rb

@@ -0,0 +1,3 @@
+module ApiNavigator
+  VERSION = '0.0.1'.freeze
+end

data/lib/faraday/connection.rb

@@ -0,0 +1,17 @@
+require 'faraday'
+require 'faraday/digestauth'
+
+module Faraday
+  # Reopen Faraday::Connection to add a helper to set the digest auth data.
+  class Connection
+    # Public: Adds the digest auth middleware at the top and sets the user and
+    # password.
+    #
+    # user     - A String with the user.
+    # password - A String with the password.
+    #
+    def digest_auth(user, password)
+      builder.insert(0, Faraday::Request::DigestAuth, user, password)
+    end
+  end
+end

data/spec/fixtures/requests.rb

@@ -0,0 +1,157 @@
+require 'json'
+
+module Fixtures
+  module Requests
+
+    # Fixtures::Requests.root_response
+    def root_response(format: :json)
+      response = {
+        _links: {
+          self:          { "href": "/" },
+          books:         { "href": "/books" },
+          filter: {
+            href: "/productions/1?categories={filter}",
+            templated: true,
+          },
+          two_links:     [
+            { "href": "/any_resource/1" },
+            { "href": "/any_resource/2" },
+          ],
+          'api:authors': { "href": "/api/authors" },
+          curies: [
+            {
+              name:      "api",
+              href:      "/docs/resources/{rel}",
+              templated: true,
+            }
+          ],
+          null_link: nil,
+        }
+      }
+
+      format == :json ? response.to_json : response
+    end
+
+    def books_response(format = :json)
+      response = {
+        data: [
+          {
+            data: {
+              title: 'Book 1',
+              body: 'Book 1 Body',
+              year: 1999,
+              publisher: {
+                data: {
+                  name: 'Manning Publisher',
+                },
+                _links: {
+                  self: {
+                    href: "http://localhost:3000/sample/publisher/1",
+                  }
+                },
+                _meta: { type: "publisher" }                              
+              },
+            },
+            _links: {
+              self: {
+                href: "http://localhost:3000/sample/books/1",
+              },
+              authors: {
+                href: "http://localhost:3000/sample/book/1/authors",
+              },
+              publisher: {
+                href: "http://localhost:3000/sample/book/1/publisher",
+              },
+            },
+            _meta: { type: "book" }                              
+          },
+          {
+            data: {
+              title: 'Book 2',
+              body: 'Book 2 Body',
+              year: 1999,
+              publisher: {
+                data: {
+                  name: 'PragBook Publisher',
+                },
+                _links: {
+                  self: {
+                    href: "http://localhost:3000/sample/publisher/2",
+                  }
+                },
+                _meta: { type: "publisher" }                              
+              },
+            },
+            _links: {
+              self: {
+                href: "http://localhost:3000/sample/books/2",
+              },
+              authors: {
+                href: "http://localhost:3000/sample/book/2/authors",
+              },
+              publisher: {
+                href: "http://localhost:3000/sample/book/2/publisher",
+              },
+            },
+            _meta: { type: "book" }                              
+          },
+        ],
+        _links: {
+          self: {
+            href: "http://localhost:3000/sample/books",
+          }
+        },
+        _meta: { total_number_of: 22 }
+      }
+
+      format == :json ? response.to_json : response
+    end
+
+    # singular resource
+    def book_response(format = :json)
+      response = {
+        data: {
+          title: 'Book 1',
+          body: 'Book 1 Body',
+          year: 1999,
+          publisher: {
+            data: {
+              name: 'Manning Publisher',
+            },
+            _links: {
+              self: {
+                href: "http://localhost:3000/sample/publisher/1",
+              }
+            },
+            _meta: { type: "book" }                              
+          },
+          authors: {
+            data: [
+              # author1,
+              # author2
+            ],
+            _links: {},
+            _meta: {}
+          }
+        },
+        _links: {
+          self: {
+            href: "http://localhost:3000/sample/books/1",
+          },
+          authors: {
+            href: "http://localhost:3000/sample/book/1/authors",
+          },
+          publisher: {
+            href: "http://localhost:3000/sample/book/1/publisher",
+          },
+        },
+        _meta: { type: "book" }                              
+      }
+
+      format == :json ? response.to_json : response
+    end
+
+    module_function :root_response, :books_response, :book_response
+
+  end
+end