europeana-api 0.5.2 → 1.0.0

data/lib/europeana/api/client.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+require 'europeana/api/faraday_middleware'
+require 'typhoeus/adapters/faraday'
+
+module Europeana
+  module API
+    ##
+    # The API client responsible for handling requests and responses
+    class Client
+      attr_reader :queue
+
+      delegate :get, :post, :put, :delete, :head, :patch, :options, to: :connection
+
+      def initialize
+        @queue = Queue.new(self)
+      end
+
+      def in_parallel?
+        @queue.present?
+      end
+
+      ##
+      # `Faraday` connection to the API
+      #
+      # * Requests are retried 5 times at an interval of 3 seconds
+      # * Requests are instrumented
+      # * JSON responses are parsed
+      #
+      # @return [Faraday::Connection]
+      def connection
+        @connection ||= begin
+          Faraday.new do |conn|
+            conn.request :instrumentation
+            conn.request :parameter_repetition
+            conn.request :authenticated_request
+            conn.request :retry, max: 5, interval: 3, exceptions: [Errno::ECONNREFUSED, EOFError]
+
+            conn.options.open_timeout = 5
+            conn.options.timeout = 45
+
+            conn.response :json_various, content_type: /\bjson$/
+            conn.response :text, content_type: %r{^text(\b[^/]+)?/(plain|html)$}
+
+            conn.adapter :typhoeus
+            conn.url_prefix = Europeana::API.url
+          end
+        end
+      end
+    end
+  end
+end

data/lib/europeana/api/entity.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+module Europeana
+  module API
+    ##
+    # Interface to the Entity API
+    #
+    # @see http://entity.europeana.eu/docs/
+    class Entity
+      include Resource
+
+      has_api_endpoint :resolve, path: '/entities/resolve'
+      has_api_endpoint :fetch, path: '/entities/%{type}/%{namespace}/%{identifier}'
+      has_api_endpoint :suggest, path: '/entities/suggest'
+    end
+  end
+end

data/lib/europeana/api/errors.rb

@@ -1,60 +1,44 @@
+# frozen_string_literal: true
 module Europeana
   module API
     module Errors
-      ##
-      # Raised if API requests are attempted without the API key having been set.
-      #
-      # @todo Use one-line error messages (in backwards-incompatible version)
-      class MissingAPIKeyError < StandardError
-        def initialize(msg = nil)
-          msg ||= <<-MSG
-  Missing API key.
-
-  The Europeana API key has not been set.
-
-  Sign up for an API key at: http://labs.europeana.eu/api/registration/
-
-  Set the key with:
+      class Base < StandardError
+        attr_reader :faraday_response
 
-    Europeana::API.api_key = "xyz"
-          MSG
-          super(msg)
+        def initialize(faraday_response)
+          @faraday_response = faraday_response
         end
       end
 
+      ##
+      # Raised if API requests are attempted without the API key having been set.
+      class MissingAPIKeyError < Base
+      end
+
       ##
       # Raised if the API response success flag is false, indicating a problem
       # with the request.
-      class RequestError < StandardError
-        def initialize(msg = nil)
-          msg ||= <<-MSG
-  Request error.
-
-  There was a problem with your request to the Europeana API.
-          MSG
-          super(msg)
-        end
+      class RequestError < Base
+      end
+
+      class ResourceNotFoundError < Base
+      end
+
+      class ClientError < Base
+      end
+
+      class ServerError < Base
       end
 
       ##
       # Raised if the API response is not valid JSON.
-      class ResponseError < StandardError
-        def initialize(msg = nil)
-          msg ||= <<-MSG
-  Response error.
-
-  Unable to parse the response from the Europeana API.
-          MSG
-          super(msg)
-        end
+      class ResponseError < Base
       end
 
-      module Request
-        ##
-        # Raised if the API response indicates invalid pagination params in
-        # the request.
-        class PaginationError < StandardError
-        end
+      ##
+      # Raised if the API response indicates invalid pagination params in
+      # the request.
+      class PaginationError < Base
       end
     end
   end

data/lib/europeana/api/faraday_middleware.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'faraday_middleware'
+
+module Europeana
+  module API
+    ##
+    # `Faraday` middleware for Europeana API specific behaviours
+    module FaradayMiddleware
+      autoload :AuthenticatedRequest, 'europeana/api/faraday_middleware/request/authenticated_request'
+      autoload :ParameterRepetition, 'europeana/api/faraday_middleware/request/parameter_repetition'
+
+      autoload :HandleText, 'europeana/api/faraday_middleware/response/handle_text'
+      autoload :ParseJsonToVarious, 'europeana/api/faraday_middleware/response/parse_json_to_various'
+
+      Faraday::Request.register_middleware \
+        authenticated_request: -> { AuthenticatedRequest },
+        parameter_repetition: -> { ParameterRepetition }
+
+      Faraday::Response.register_middleware \
+        text: -> { HandleText },
+        json_various: -> { ParseJsonToVarious }
+    end
+  end
+end

data/lib/europeana/api/faraday_middleware/request/authenticated_request.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+require 'rack'
+
+module Europeana
+  module API
+    module FaradayMiddleware
+      ##
+      # `Faraday` middleware to handle Europeana API authentication
+      class AuthenticatedRequest < Faraday::Middleware
+        def call(env)
+          ensure_api_key(env)
+          @app.call env
+        end
+
+        def ensure_api_key(env)
+          query = Rack::Utils.parse_query(env.url.query)
+          return if query.key?('wskey')
+
+          query['wskey'] = Europeana::API.key
+          env.url.query = Rack::Utils.build_query(query)
+        end
+      end
+    end
+  end
+end

data/lib/europeana/api/faraday_middleware/request/parameter_repetition.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+module Europeana
+  module API
+    module FaradayMiddleware
+      ##
+      # Handles multiple URL params with the same name
+      #
+      # Europeana's APIs expect params with the same name to appear in URL
+      # queries like `?qf=this&qf=that`, but Faraday constructs them the
+      # Rack/Rails way, like `?qf[]=this&qf[]=that`. This middleware constructs
+      # them to the former format, using `Rack::Utils.build_query`.
+      class ParameterRepetition < Faraday::Middleware
+        def call(env)
+          repeat_query_parameters(env)
+          @app.call env
+        end
+
+        def repeat_query_parameters(env)
+          query = Rack::Utils.parse_nested_query(env.url.query)
+          env.url.query = Rack::Utils.build_query(query)
+        end
+      end
+    end
+  end
+end

data/lib/europeana/api/faraday_middleware/response/handle_text.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+require 'faraday_middleware/response_middleware'
+
+module Europeana
+  module API
+    module FaradayMiddleware
+      ##
+      # Handles plain text & HTML responses from the API, which are never desired
+      class HandleText < ::FaradayMiddleware::ResponseMiddleware
+        def process_response(env)
+          super
+          content_type = env.response_headers['Content-Type']
+          fail Europeana::API::Errors::ResponseError.new(env),
+               %(API responded with Content-Type "#{content_type}" and status #{env[:status]})
+        end
+      end
+    end
+  end
+end

data/lib/europeana/api/faraday_middleware/response/parse_json_to_various.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+require 'faraday_middleware/response_middleware'
+require 'active_support/json'
+
+module Europeana
+  module API
+    module FaradayMiddleware
+      ##
+      # Handles JSON parsing of API responses
+      #
+      # Returns the response as either a `Hash` (default) or an `OpenStruct`.
+      #
+      # To set the response format to be `OpenStruct`:
+      # ```ruby
+      # Europeana::API.configure do |config|
+      #   config.parse_json_to = OpenStruct
+      # end
+      # ```
+      #
+      # If using `OpenStruct`, changes "-" in JSON field keys to "_", so that
+      # they become methods.
+      class ParseJsonToVarious < ::FaradayMiddleware::ResponseMiddleware
+        dependency do
+          require 'json' unless defined?(JSON)
+        end
+
+        define_parser do |body|
+          unless body.strip.empty?
+            hash = JSON.parse(body)
+            if Europeana::API.configuration.parse_json_to == OpenStruct
+              underscored_hash = underscore_hash_keys(hash)
+              underscored_body = underscored_hash.to_json
+              JSON.parse(underscored_body, object_class: OpenStruct)
+            else
+              hash.with_indifferent_access
+            end
+          end
+        end
+
+        class << self
+          def underscore_hash_keys(hash)
+            hash.keys.each do |k|
+              hash[k] = underscore_hash_keys(hash[k]) if hash[k].is_a?(Hash)
+              hash[k.underscore] = hash.delete(k) if k =~ /-/
+            end
+            hash
+          end
+        end
+      end
+    end
+  end
+end

data/lib/europeana/api/logger.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+require 'active_support/notifications'
+
+# Subscribe to Faraday request instrumentation
+ActiveSupport::Notifications.subscribe('request.faraday') do |_name, starts, ends, _id, env|
+  url = env[:url]
+  http_method = env[:method].to_s.upcase
+  duration = ends - starts
+  Europeana::API.logger.info(format('%s %s (%.3f s)', http_method, url, duration))
+end

data/lib/europeana/api/queue.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+module Europeana
+  module API
+    ##
+    # A queue of API requests to run in parallel
+    class Queue
+      Item = Struct.new(:resource, :method, :params)
+
+      attr_reader :client
+
+      def initialize(client)
+        @client = client
+        @items = []
+      end
+
+      def present?
+        @items.present?
+      end
+
+      def add(resource, method, **params)
+        @items << Item.new(resource, method, **params)
+      end
+
+      def run
+        responses = []
+
+        client.connection.in_parallel do
+          @items.each do |item|
+            resource_class = Europeana::API.send(item.resource)
+            request = resource_class.send(:api_request_for_endpoint, item.method, item.params)
+            request.client = client
+            responses << request.execute
+          end
+        end
+
+        responses.map do |response|
+          begin
+            response.validate!
+            response.body
+          rescue StandardError => exception
+            exception
+          end
+        end
+      end
+    end
+  end
+end

data/lib/europeana/api/record.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 module Europeana
   module API
     ##
@@ -5,93 +6,38 @@ module Europeana
     #
     # @see http://labs.europeana.eu/api/record/
     class Record
-      autoload :Hierarchy, 'europeana/api/record/hierarchy'
-
-      include Requestable
-
-      # Europeana ID of the record
-      attr_reader :id
-
-      # Request parameters to send to the API
-      attr_reader :params
-
-      ##
-      # @param [String] id Europeana ID of the record
-      # @param [Hash] params Request parameters
-      def initialize(id, params = {})
-        self.request_params = params
-        @id = id
-      end
-
-      ##
-      # Sets record ID attribute after validating format.
-      #
-      # @param [String] id Record ID
-      #
-      def id=(id)
-        unless id.is_a?(String) && id.match(%r{\A/[^/]+/[^/]+\B})
-          fail ArgumentError, "Invalid Europeana record ID: \"#{id}\""
-        end
-        @id = id
-      end
-
-      ##
-      # Sets request parameters after validating keys
-      #
-      # Valid parameter keys:
-      # * :callback
-      #
-      # For explanations of these request parameters, see: http://labs.europeana.eu/api/record/
-      #
-      # @param (see #initialize)
-      # @return [Hash] Request parameters
-      def params=(params = {})
-        params.assert_valid_keys(:callback, :wskey)
-        @params = params
-      end
-
-      ##
-      # Gets the URL for this Record request
-      #
-      # @param [Hash{Symbol => Object}] options
-      # @option options [Boolean] :ld (false)
-      #   Request JSON-LD
-      # @return [String]
-      def request_url(options = {})
-        options.assert_valid_keys(:ld)
-        (api_url + "/record#{@id}.json").tap do |url|
-          url << 'ld' if options[:ld]
-        end
+      include Resource
+
+      has_api_endpoint :search,
+                       path: '/v2/search.json',
+                       errors: {
+                         'Invalid query parameter' => Errors::RequestError,
+                         /1000 search results/ => Errors::PaginationError
+                       }
+      has_api_endpoint :fetch, path: '/v2/record%{id}.json'
+
+      # Hierarchies
+      %w(self parent children preceding_siblings following_siblings ancestor_self_siblings).each do |hierarchical|
+        has_api_endpoint hierarchical.to_sym, path: "/v2/record%{id}/#{hierarchical.dasherize}.json"
       end
 
-      alias_method :get, :execute_request
-
-      ##
-      # Examines the `success` and `error` fields of the response for failure
-      #
-      # @raise [Europeana::Errors::RequestError] if API response has
-      #   `success:false`
-      # @raise [Europeana::Errors::RequestError] if API response has 404 status
-      #   code
-      # @see Requestable#parse_response
-      def parse_response(response, options = {})
-        super.tap do |body|
-          if (options[:ld] && !(200..299).include?(response.code.to_i)) || (!options[:ld] && !body[:success])
-            fail Errors::RequestError, (body.key?(:error) ? body[:error] : response.code)
+      class << self
+        ##
+        # Escapes Lucene syntax special characters for use in query parameters.
+        #
+        # The `Europeana::API` gem does not perform this escaping itself.
+        # Applications using the gem are responsible for escaping parameters
+        # when needed.
+        #
+        # @param [String] text Text to escape
+        # @return [String] Escaped text
+        def escape(text)
+          fail ArgumentError, "Expected String, got #{text.class}" unless text.is_a?(String)
+          specials = %w<\\ + - & | ! ( ) { } [ ] ^ " ~ * ? : />
+          specials.each_with_object(text.dup) do |char, unescaped|
+            unescaped.gsub!(char, '\\\\' + char) # prepends *one* backslash
           end
         end
-      rescue JSON::ParserError
-        if response.code.to_i == 404
-          # Handle HTML 404 responses on malformed record ID, emulating API's
-          # JSON response.
-          raise Errors::RequestError, "Invalid record identifier: #{@id}"
-        else
-          raise
-        end
-      end
-
-      def hierarchy
-        @hierarchy ||= Hierarchy.new(id)
       end
     end
   end