eipiai 0.6.0 → 0.7.0

data/lib/eipiai/roar/representers/api.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 require 'eipiai/roar/representers/base'
 
 module Eipiai
@@ -12,23 +13,33 @@ module Eipiai
 
     def self.populate_from_app(app)
       app.routes.each do |route|
-        next unless route.resource.respond_to?(:link_identifier)
+        resource = route.resource.new(nil, nil)
+        next unless resource.respond_to?(:resource_relation) && resource.top_level_relation?
 
-        templated = route.path_spec.any? { |r| r.is_a?(Symbol) }
-        options = { rel: route.resource.link_identifier }
-        options.merge!(templated: templated) if templated
+        options = {
+          rel: resource.resource_relation,
+          templated: templated?(route)
+        }
 
-        add_route(route, options)
+        add_route(route, resource.query_keys, options.compact)
       end
     end
 
-    def self.add_route(route, options)
+    def self.add_route(route, query_keys, options)
       link(options) do |context|
         request = context[:request]
         path    = '/' + route.path_spec.map { |e| e.is_a?(Symbol) ? "{#{e}}" : e }.join('/')
+        path   += "{?#{query_keys.join(',')}}" if query_keys.any?
 
         request.present? ? Addressable::URI.parse(request.uri).merge(path: path).to_s : path
       end
     end
+
+    def self.templated?(route)
+      query_keys = route.resource.new(nil, nil).query_keys
+      templated  = query_keys.any? || route.path_spec.map(&:class).include?(Symbol)
+
+      templated || nil
+    end
   end
 end

data/lib/eipiai/roar/representers/base.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 require 'addressable/uri'
 require 'roar'
 require 'roar/decorator'

data/lib/eipiai/validation.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 require 'eipiai/validation/concerns/formatted_errors'
 
 require 'eipiai/validation/validators/base'

data/lib/eipiai/validation/concerns/formatted_errors.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 # FormattedErrors
 #
 # copy/paste of the https://github.com/blendle/formatted_errors gem, until that

data/lib/eipiai/validation/validators/base.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 module Eipiai
   # Validator
   #
@@ -48,7 +49,7 @@ module Eipiai
     # @return [void]
     #
     def validate
-      fail NotImplementedError, '#validate required'
+      raise NotImplementedError, '#validate required'
     end
 
     # errors

data/lib/eipiai/validation/validators/sequel.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 require 'eipiai/validation/validators/base'
 
 module Eipiai

data/lib/eipiai/version.rb

@@ -1,7 +1,8 @@
+# frozen_string_literal: true
 # Eipiai
 #
 # The current version of the Eipiai library.
 #
 module Eipiai
-  VERSION = '0.6.0'
+  VERSION = '0.7.0'
 end

data/lib/eipiai/webmachine.rb

@@ -1,9 +1,11 @@
+# frozen_string_literal: true
 require 'webmachine'
 
 require 'eipiai/webmachine/ext/decision'
 require 'eipiai/webmachine/ext/request'
 
 require 'eipiai/webmachine/resources/concerns/objectifiable'
+require 'eipiai/webmachine/resources/concerns/representable'
 
 require 'eipiai/webmachine/resources/api'
 require 'eipiai/webmachine/resources/base'

data/lib/eipiai/webmachine/ext/decision.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 require 'webmachine'
 
 module Webmachine

data/lib/eipiai/webmachine/ext/request.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 require 'addressable/uri'
 require 'webmachine'
 
@@ -38,7 +39,7 @@ module Webmachine
     module URIReplacement
       # build_uri
       #
-      # Given an uri object, and headers, calls  `Webmachine::Request#build_uri`
+      # Given an uri object, and headers, calls `Webmachine::Request#build_uri`
       # and parses the result using Addressable (if available), or simply
       # returns the result as-is.
       #

data/lib/eipiai/webmachine/resources/api.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 require 'eipiai/webmachine/resources/base'
 
 require 'active_support/core_ext/string/inflections'
@@ -15,13 +16,16 @@ module Eipiai
 
   # ApiResource
   #
-  # The base resource which can be included in regular Webmachine::Resource
-  # objects. It provides sensible defaults for a full-features REST API
-  # endpoint.
+  # The API resource handles the /api endpoint, which is the main entrypoint for
+  # all HyperMedia based API requests.
   #
   class ApiResource < Webmachine::Resource
     include Resource
 
+    def top_level_relation?
+      true
+    end
+
     def allowed_methods
       %w(GET)
     end

data/lib/eipiai/webmachine/resources/base.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 require 'eipiai/webmachine/resources/singular'
 require 'eipiai/webmachine/resources/collection'
 
@@ -13,6 +14,7 @@ module Eipiai
   #
   module Resource
     include Objectifiable
+    include Representable
 
     # Includes the correct resource into the class, depending on its name.
     #
@@ -27,8 +29,57 @@ module Eipiai
       else
         base.send(:include, CollectionResource)
       end
+    end
+
+    # resource_relation
+    #
+    # The name to be used when linking to this resource as a relation.
+    #
+    # The string returned from this method will become the name of the link in
+    # the HAL+JSON representation of this resource.
+    #
+    # @example
+    #   resource.resource_relation # => 'items'
+    #
+    # @return [String] resource relation name
+    #
+    def resource_relation
+      resource_name.demodulize.underscore
+    end
+
+    # top_level_relation?
+    #
+    # return `true` if the link relation to this resource should be added to the
+    # top-level API entrypoint.
+    #
+    # It is good practice to keep most link relations out of the top-level
+    # entrypoint, instead opting for nesting the resource within its parent
+    # resource links relations.
+    #
+    # @return [true, false]
+    #
+    def top_level_relation?
+      false
+    end
+
+    # query_keys
+    #
+    # Returns an array of optional query component keys this resource accepts.
+    # The keys are added to the link relation as templated variables.
+    #
+    # Defaults to an empty array, not exposing any optional query keys.
+    #
+    # @return [Array<String>] array of query keys
+    #
+    def query_keys
+      []
+    end
 
-      base.extend(ClassMethods)
+    def service_available?
+      return true if Eipiai::HealthCheck.new.healthy?
+
+      response.headers['Retry-After'] = '60'
+      false
     end
 
     # malformed_request?
@@ -76,13 +127,17 @@ module Eipiai
     end
 
     def content_types_provided
-      [['application/hal+json', :to_json]]
+      [['application/hal+json', :to_hal_json], ['application/json', :to_json]]
     end
 
     def content_types_accepted
       [['application/json', :from_json]]
     end
 
+    def post_is_create?
+      true
+    end
+
     # params
     #
     # Given a string in JSON format, returns the hash representation of that
@@ -107,12 +162,12 @@ module Eipiai
       {}
     end
 
-    # to_hash
+    # to_h
     #
-    # Given an object, calls `#to_hash` on that object,
+    # Given an object, calls `#to_h` on that object,
     #
-    # If the object's `to_hash` implementation accepts any arguments, the
-    # hash `{ request: request }` is sent as its first argument.
+    # If the object's `to_h` implementation accepts any arguments, the hash
+    # `{ request: request }` is sent as its first argument.
     #
     # In practice, this method is used without any parameters, causing the
     # method to call `represented`, which represents a Roar representer. This in
@@ -122,17 +177,23 @@ module Eipiai
     # @example
     #   item = Item.new(uid: 'hello')
     #   get('/item/hello')
-    #   resource.to_hash(item)['uid'] # => 'hello'
+    #   resource.to_h(item)['uid'] # => 'hello'
     #
-    # @param [Object] obj to call #to_hash on
+    # @param [Object] obj to call #to_h on
     # @return [Hash] hash representation of the object
     #
-    def to_hash(obj = object)
-      obj.method(:to_hash).arity.zero? ? obj.to_hash : obj.to_hash(request: request)
+    def to_h(obj = object)
+      obj.method(:to_h).arity.zero? ? obj.to_h : obj.to_h(request: request)
+    rescue
+      obj
     end
 
     def to_json
-      to_hash.to_json
+      to_h.to_json
+    end
+
+    def to_hal_json
+      to_h.to_json
     end
 
     # new_object
@@ -154,6 +215,14 @@ module Eipiai
       @new_object ||= object_class.new.from_hash(params)
     end
 
+    def base_uri
+      request.base_uri
+    end
+
+    def create_uri
+      Addressable::URI.join(base_uri, create_path)
+    end
+
     private
 
     def json_error_body(errors)
@@ -162,14 +231,22 @@ module Eipiai
       true
     end
 
-    # ClassMethods
-    #
-    # These methods will be defined on the class in which this module is
-    # included.
-    #
-    module ClassMethods
-      def link_identifier
-        name.chomp('Resource').demodulize.underscore.to_sym
+    def content_type_handler
+      content_type = request.headers['accept']
+      media_type   = Webmachine::MediaType.parse(content_type)
+
+      content_types_provided.find { |ct, _| media_type.type_matches?(ct) }.last
+    rescue ArgumentError
+      nil
+    end
+
+    def handle_post_or_put_with_optional_content(created: true)
+      if content_type_handler
+        response.body = send(content_type_handler)
+        created ? 201 : 200
+      else
+        response.headers['Location'] ||= create_uri.to_s
+        created ? 201 : 204
       end
     end
   end

data/lib/eipiai/webmachine/resources/collection.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 require 'eipiai/webmachine/resources/base'
 
 module Eipiai
@@ -15,33 +16,18 @@ module Eipiai
       %w(GET POST)
     end
 
-    def post_is_create?
-      true
-    end
-
     def create_path
       new_object.path
     end
 
     def from_json
-      new_object.save && handle_post_response
+      new_object.save
+      handle_post_or_put_with_optional_content
     end
 
     private
 
-    def content_type_handler
-      content_type = response.headers[Webmachine::CONTENT_TYPE]
-      media_type   = Webmachine::MediaType.parse(content_type)
-
-      content_types_provided.find { |ct, _| media_type.type_matches?(ct) }.last
-    end
-
-    def handle_post_response
-      response.body = send(content_type_handler)
-      true
-    end
-
-    def to_hash
+    def to_h
       super(request.get? ? object : new_object)
     end
 

data/lib/eipiai/webmachine/resources/concerns/objectifiable.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 module Eipiai
   module Resource
     # Objectifiable

data/lib/eipiai/webmachine/resources/concerns/representable.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+module Eipiai
+  module Resource
+    # Representable
+    #
+    # When included in a resource, provides basic methods to get to the
+    # "representer" that can be used to represent the object that the resource
+    # provides access to.
+    #
+    module Representable
+      private
+
+      # resource_name
+      #
+      # Take the resource class name, and strip `Resource` part from the name.
+      #
+      # @example
+      #   resource.send :resource_name # => 'Eipiai::TestApp::Items'
+      #
+      # @return [String] resource name
+      #
+      def resource_name
+        self.class.name.chomp('Resource')
+      end
+
+      # singular_representer_class
+      #
+      # Constant, representing the representer belonging to the defined
+      # `object`.
+      #
+      # If the resource is called `ItemResource`, the representer will be
+      # `ItemRepresenter`.
+      #
+      # Returns `nil` if constant does not exist.
+      #
+      # @example
+      #   resource.send :singular_representer_class # => ItemRepresenter
+      #
+      # @return [Class, nil] representer class, or nil if not found
+      #
+      def singular_representer_class
+        "#{resource_name.singularize}Representer".constantize
+      rescue NameError
+        nil
+      end
+
+      # collection_representer_class
+      #
+      # Constant, representing the representer belonging to the defined
+      # collection of `object`s.
+      #
+      # If the resource is called `ItemResource`, the representer will be
+      # `ItemsRepresenter`.
+      #
+      # Returns `nil` if constant does not exist.
+      #
+      # @example
+      #   resource.send :collection_representer_class # => ItemsRepresenter
+      #
+      # @return [Class, nil] representer class, or nil if not found
+      #
+      def collection_representer_class
+        "#{resource_name.pluralize}Representer".constantize
+      rescue NameError
+        nil
+      end
+    end
+  end
+end