api_navigator 0.0.1

data/lib/api_navigator.rb

@@ -0,0 +1,45 @@
+require 'api_navigator/collection_hash'
+require 'api_navigator/link'
+require 'api_navigator/attributes'
+require 'api_navigator/curie'
+require 'api_navigator/entry_point'
+require 'api_navigator/link_collection'
+require 'api_navigator/resource'
+require 'api_navigator/resources/member_resource'
+require 'api_navigator/resources/collection_resource'
+require 'api_navigator/version'
+
+# 
+# @author [martinschweizer]
+# 
+module ApiNavigator
+
+  ClientResourceClasses = {}
+
+  # @param url [String] The base url
+  # @param &block [type] Block for configuring the navitgator
+  # 
+  # @return [ApiNavigator::EntryPoint] Then entrypoint hoocking it all up
+  def self.new(url, client_identifier=nil, &block)
+    ApiNavigator::EntryPoint.new(url, client_identifier, &block)
+  end
+
+  class << self
+    def register(client_identifier)
+      raise "Already registered client_identifier: #{client_identifier}" if ClientResourceClasses.include?(client_identifier)
+
+      ClientResourceClasses[client_identifier] = {}
+    end
+
+    def register_resource(identifier, resource_class, client_identifier:)
+      ClientResourceClasses.fetch(client_identifier)[identifier] = resource_class
+    end
+
+    def resource_class(identifier, client_identifier:)
+      result = ClientResourceClasses.fetch(client_identifier, {}).fetch(identifier, nil)
+
+      result.nil? ? ApiNavigator::Resources::MemberResource : result
+    end
+  end
+
+end

data/lib/api_navigator/attributes.rb

@@ -0,0 +1,20 @@
+module ApiNavigator
+  # Public: A wrapper class to easily acces the attributes in a Resource.
+  #
+  # Examples
+  #
+  #   resource.attributes['title']
+  #   resource.attributes.title
+  #
+  class Attributes < CollectionHash
+    # Public: Initializes the Attributes of a Resource.
+    #
+    # representation - The hash with the HAL representation of the Resource.
+    #
+    def initialize(attributes_hash)
+      raise ArgumentError, "argument nust be a Hash, is #{attributes_hash.class}" unless attributes_hash.kind_of? Hash
+      super
+    end
+
+  end
+end

data/lib/api_navigator/collection_hash.rb

@@ -0,0 +1,90 @@
+module ApiNavigator
+  # Public: A helper class to wrap a collection of elements and provide
+  # Hash-like access or via a method call.
+  #
+  # Examples
+  #
+  #  collection['value']
+  #  collection.value
+  #
+  class CollectionHash
+    include Enumerable
+
+    # Public: Initializes the Collection.
+    #
+    # collection - The Hash to be wrapped.
+    def initialize(collection)
+      @collection = collection
+    end
+
+    # Public: Each implementation to allow the class to use the Enumerable
+    # benefits.
+    #
+    # Returns an Enumerator.
+    def each(&block)
+      @collection.each(&block)
+    end
+
+    # Public: Checks if this collection includes a given key.
+    #
+    # key - A String or Symbol to check for existance.
+    #
+    # Returns True/False.
+    def include?(key)
+      @collection.include?(key)
+    end
+
+    # Public: Returns a value from the collection for the given key.
+    # If the key can't be found, there are several options:
+    # With no other arguments, it will raise an KeyError exception;
+    # if default is given, then that will be returned;
+    #
+    # key - A String or Symbol of the value to get from the collection.
+    # default - An optional value to be returned if the key is not found.
+    #
+    # Returns an Object.
+    def fetch(*args)
+      @collection.fetch(*args)
+    end
+
+    # Public: Provides Hash-like access to the collection.
+    #
+    # name - A String or Symbol of the value to get from the collection.
+    #
+    # Returns an Object.
+    def [](name)
+      @collection[name.to_s]
+    end
+
+    # Public: Returns the wrapped collection as a Hash.
+    #
+    # Returns a Hash.
+    def to_h
+      @collection.to_hash
+    end
+    alias to_hash to_h
+
+    def to_s
+      to_hash
+    end
+
+    # Public: Provides method access to the collection values.
+    #
+    # It allows accessing a value as `collection.name` instead of
+    # `collection['name']`
+    #
+    # Returns an Object.
+    def method_missing(method_name, *_args, &_block)
+      @collection.fetch(method_name.to_s) do
+        raise "Could not find `#{method_name}` in #{self.class.name}"
+      end
+    end
+
+    # Internal: Accessory method to allow the collection respond to the
+    # methods that will hit method_missing.
+    def respond_to_missing?(method_name, _include_private = false)
+      @collection.include?(method_name.to_s)
+    end
+
+  end
+end

data/lib/api_navigator/curie.rb

@@ -0,0 +1,47 @@
+module ApiNavigator
+  # Internal: Curies are named tokens that you can define in the document and use
+  # to express curie relation URIs in a friendlier, more compact fashion.
+  #
+  class Curie
+    # Public: Initializes a new Curie.
+    #
+    # curie_hash  - The String with the URI of the curie.
+    # entry_point - The EntryPoint object to inject the configuration.
+    def initialize(curie_hash, entry_point)
+      @curie_hash = curie_hash
+      @entry_point = entry_point
+    end
+
+    # Public: Indicates if the curie is an URITemplate or a regular URI.
+    #
+    # Returns true if it is templated.
+    # Returns false if it not templated.
+    def templated?
+      !!@curie_hash['templated']
+    end
+
+    # Public: Returns the name property of the Curie.
+    def name
+      @curie_hash['name']
+    end
+
+    # Public: Returns the href property of the Curie.
+    def href
+      @curie_hash['href']
+    end
+
+    def inspect
+      "#<#{self.class.name} #{@curie_hash}>"
+    end
+
+    # Public: Expands the Curie when is templated with the given variables.
+    #
+    # rel - The String rel to expand.
+    #
+    # Returns a new expanded url.
+    def expand(rel)
+      return rel unless rel && templated?
+      href.gsub('{rel}', rel) if href
+    end
+  end
+end

data/lib/api_navigator/entry_point.rb

@@ -0,0 +1,157 @@
+require 'faraday_middleware'
+require 'faraday_hal_middleware'
+require_relative '../faraday/connection'
+
+module ApiNavigator
+  # Public: Exception that is raised when trying to modify an
+  # already initialized connection.
+  class ConnectionAlreadyInitializedError < StandardError
+    # Public: Returns a String with the exception message.
+    def message
+      'The connection has already been initialized.'
+    end
+  end
+
+  # Public: The EntryPoint is the main public API for ApiNavigator. It is used to
+  # initialize an API client and setup the configuration.
+  #
+  # Examples
+  #
+  #  client = ApiNavigator::EntryPoint.new('http://my.api.org')
+  #
+  #  client = ApiNavigator::EntryPoint.new('http://my.api.org') do |entry_point|
+  #    entry_point.connection do |conn|
+  #      conn.use Faraday::Request::OAuth
+  #    end
+  #    entry_point.headers['Access-Token'] = 'token'
+  #  end
+  #
+  class EntryPoint < Link
+    extend Forwardable
+
+    attr_reader :client_identifier
+    
+    # Public: Delegates common methods to be used with the Faraday connection.
+    def_delegators :connection, :basic_auth, :digest_auth, :token_auth, :params, :params=
+    
+    # Public: Initializes an EntryPoint.
+    #
+    # url    - A String with the entry point of your API.
+    def initialize(url, client_identifier=nil, &_block)
+      @link = { 'href' => url }
+      @entry_point = self
+      @options = {}
+      @connection = nil
+      @resource = nil
+      @key = nil
+      @uri_variables = nil
+      @client_identifier = client_identifier
+      yield self if block_given?
+    end
+
+    # Public: A Faraday connection to use as a HTTP client.
+    #
+    # options - A Hash containing additional options to pass to Farday. Use
+    # {default: false} if you want to skip using default Faraday options set by
+    # ApiNavigator.
+    #
+    # Returns a Faraday::Connection.
+    def connection(options = {}, &block)
+      @faraday_options ||= options.dup
+      if block_given?
+        raise ConnectionAlreadyInitializedError if @connection
+        @faraday_block = if @faraday_options.delete(:default) == false
+                           block
+                         else
+                           lambda do |conn|
+                             default_faraday_block.call conn
+                             yield conn
+                           end
+                         end
+      else
+        @connection ||= Faraday.new(_url, faraday_options, &faraday_block)
+      end
+    end
+
+    # Public: Headers included with every API request.
+    #
+    # Returns a Hash.
+    def headers
+      return @connection.headers if @connection
+      @headers ||= default_headers
+    end
+
+    # Public: Set headers.
+    #
+    # value    - A Hash containing headers to include with every API request.
+    def headers=(value)
+      raise ConnectionAlreadyInitializedError if @connection
+      @headers = value
+    end
+
+    # Public: Options passed to Faraday
+    #
+    # Returns a Hash.
+    def faraday_options
+      (@faraday_options ||= {}).merge(headers: headers)
+    end
+
+    # Public: Set Faraday connection options.
+    #
+    # value    - A Hash containing options to pass to Faraday
+    def faraday_options=(value)
+      raise ConnectionAlreadyInitializedError if @connection
+      @faraday_options = value
+    end
+
+    # Public: Faraday block used with every API request.
+    #
+    # Returns a Proc.
+    def faraday_block
+      @faraday_block ||= default_faraday_block
+    end
+
+    # Public: Set a Faraday block to use with every API request.
+    #
+    # value    - A Proc accepting a Faraday::Connection.
+    def faraday_block=(value)
+      raise ConnectionAlreadyInitializedError if @connection
+      @faraday_block = value
+    end
+
+    # Public: Read/Set options.
+    #
+    # value    - A Hash containing the client options.
+    attr_accessor :options
+
+    private
+
+    # Internal: Returns a block to initialize the Faraday connection. The
+    # default block includes a middleware to encode requests as JSON, a
+    # response middleware to parse JSON responses and sets the adapter as
+    # NetHttp.
+    #
+    # These middleware can always be changed by accessing the Faraday
+    # connection.
+    #
+    # Returns a block.
+    def default_faraday_block
+      lambda do |connection|
+        connection.use Faraday::Response::RaiseError
+        connection.use FaradayMiddleware::FollowRedirects
+        connection.request :hal_json
+        connection.response :hal_json, content_type: /\bjson$/
+        connection.adapter :net_http
+        connection.options.params_encoder = Faraday::FlatParamsEncoder
+      end
+    end
+
+    # Internal: Returns the default headers to initialize the Faraday connection.
+    # The default headers et the Content-Type and Accept to application/json.
+    #
+    # Returns a Hash.
+    def default_headers
+      { 'Content-Type' => 'application/hal+json', 'Accept' => 'application/hal+json,application/json' }
+    end
+  end
+end

data/lib/api_navigator/link.rb

@@ -0,0 +1,160 @@
+require 'uri_template'
+
+module ApiNavigator
+  # Internal: The Link is used to let a Resource interact with the API.
+  #
+  class Link
+    # Public: Initializes a new Link.
+    #
+    # key           - The key or name of the link.
+    # link          - The String with the URI of the link.
+    # entry_point   - The EntryPoint object to inject the configuration.
+    # uri_variables - The optional Hash with the variables to expand the link
+    #                 if it is templated.
+    def initialize(key, link, entry_point, uri_variables = nil)
+      @key           = key
+      @link          = link
+      @entry_point   = entry_point
+      @uri_variables = uri_variables
+      @resource      = nil
+    end
+
+    # Public: Indicates if the link is an URITemplate or a regular URI.
+    #
+    # Returns true if it is templated.
+    # Returns false if it not templated.
+    def _templated?
+      !!@link['templated']
+    end
+
+    # Public: Expands the Link when is templated with the given variables.
+    #
+    # uri_variables - The Hash with the variables to expand the URITemplate.
+    #
+    # Returns a new Link with the expanded variables.
+    def _expand(uri_variables = {})
+      self.class.new(@key, @link, @entry_point, uri_variables)
+    end
+
+    # Public: Returns the url of the Link.
+    def _url
+      return @link['href'] unless _templated?
+      @url ||= _uri_template.expand(@uri_variables || {})
+    end
+
+    # Public: Returns an array of variables from the URITemplate.
+    #
+    # Returns an empty array for regular URIs.
+    def _variables
+      _uri_template.variables
+    end
+
+    # Public: Returns the type property of the Link
+    def _type
+      @link['type']
+    end
+
+    # Public: Returns the name property of the Link
+    def _name
+      @link['name']
+    end
+
+    # Public: Returns the deprecation property of the Link
+    def _deprecation
+      @link['deprecation']
+    end
+
+    # Public: Returns the profile property of the Link
+    def _profile
+      @link['profile']
+    end
+
+    # Public: Returns the title property of the Link
+    def _title
+      @link['title']
+    end
+
+    # Public: Returns the hreflang property of the Link
+    def _hreflang
+      @link['hreflang']
+    end
+
+    def _resource
+      @resource || _get
+    end
+
+    # Public: Returns the Resource which the Link is pointing to.
+    def _get
+      http_method(:get)
+    end
+
+    def _options
+      http_method(:options)
+    end
+
+    def _head
+      http_method(:head)
+    end
+
+    def _delete
+      http_method(:delete)
+    end
+
+    def _post(params = {})
+      http_method(:post, params)
+    end
+
+    def _put(params = {})
+      http_method(:put, params)
+    end
+
+    def _patch(params = {})
+      http_method(:patch, params)
+    end
+
+    def inspect
+      "#<#{self.class.name}(#{@key}) #{@link}>"
+    end
+
+    def to_s
+      _url
+    end
+
+    private
+
+    # Internal: Delegate the method further down the API if the resource cannot serve it.
+    def method_missing(method, *args, &block)
+      if _resource.respond_to?(method.to_s)
+        _resource.send(method, *args, &block)
+      else
+        super
+      end
+    end
+
+    # Internal: Accessory method to allow the link respond to the
+    # methods that will hit method_missing.
+    def respond_to_missing?(method, _include_private = false)
+      _resource.respond_to?(method.to_s)
+    end
+
+    # Internal: avoid delegating to resource
+    #
+    # #to_ary is called for implicit array coercion (such as parallel assignment
+    # or Array#flatten). Returning nil tells Ruby that this record is not Array-like.
+    def to_ary
+      nil
+    end
+
+    # Internal: Memoization for a URITemplate instance
+    def _uri_template
+      @uri_template ||= URITemplate.new(@link['href'])
+    end
+
+    def http_method(method, body = nil)
+      @resource = begin
+        response = @entry_point.connection.run_request(method, _url, body, nil)
+        Resource.from_representation(response.body, @entry_point, response)
+      end
+    end
+  end
+end