europeana-api 0.5.2 → 1.0.0

data/lib/europeana/api/request.rb

@@ -1,51 +1,90 @@
-require 'active_support/benchmarkable'
-require 'net/http'
-
+# frozen_string_literal: true
 module Europeana
   module API
     ##
-    # Europeana API request
+    # An API request
     class Request
-      include ActiveSupport::Benchmarkable
-
-      # Request URI
-      attr_reader :uri
-
-      # API response
-      attr_reader :response
-
-      # @param [URI]
-      def initialize(uri)
-        @uri = uri
-      end
-
-      # @return (see Net::HTTP#request)
-      def execute
-        http = Net::HTTP.new(uri.host, uri.port)
-        http.use_ssl = (uri.scheme == 'https')
-        request = Net::HTTP::Get.new(uri.request_uri)
-        retries = Europeana::API.max_retries
-
-        begin
-          attempt = Europeana::API.max_retries - retries + 1
-          logger.info("[Europeana::API] Request URL: #{uri}")
-          benchmark("[Europeana::API] Request query (attempt ##{attempt})", level: :info) do
-            @response = http.request(request)
-          end
-        rescue Timeout::Error, Errno::ECONNREFUSED, EOFError
-          retries -= 1
-          raise unless retries > 0
-          logger.warn("[Europeana::API] Network error; sleeping #{Europeana::API.retry_delay}s")
-          sleep Europeana::API.retry_delay
-          retry
-        end
+      attr_reader :endpoint
+      attr_reader :params
+      attr_reader :api_url
+      attr_reader :headers
+      attr_reader :body
+      attr_writer :client
+
+      ##
+      # @param endpoint [Hash] endpoint options
+      # @param params [Hash]
+      def initialize(endpoint, params = {})
+        @endpoint = endpoint
+        @params = params.dup
+        extract_special_params
+      end
+
+      ##
+      # @return [Response]
+      def execute(&block)
+        response = Response.new(self, faraday_response(&block))
+        return response if client.in_parallel?
+
+        response.validate!
+        response.body
+      end
+
+      def url
+        build_api_url(format_params)
+      end
+
+      def client
+        @client ||= Client.new
+      end
+
+      protected
+
+      def extract_special_params
+        @api_url = @params.delete(:api_url)
+        @headers = @params.delete(:headers)
+        @body = @params.delete(:body) unless http_method == :get
+      end
 
-        @response
+      def faraday_response
+        client.send(http_method) do |request|
+          request.url(url)
+          request.params = query_params
+          request.headers.merge!(endpoint[:headers] || {}).merge!(headers || {})
+          request.body = body unless http_method == :get
+          yield(request) if block_given?
+          # logger.debug("API request: #{request.inspect}")
+        end
       end
 
       def logger
         Europeana::API.logger
       end
+
+      def http_method
+        endpoint[:method] || :get
+      end
+
+      def format_params
+        params.slice(*endpoint_path_format_keys)
+      end
+
+      def query_params
+        params.except(*endpoint_path_format_keys)
+      end
+
+      def endpoint_path_format_keys
+        @endpoint_path_format_keys ||= endpoint[:path].scan(/%\{(.*?)\}/).flatten.map(&:to_sym)
+      end
+
+      def build_api_url(params = {})
+        request_path = format(endpoint[:path], params)
+        if api_url.nil?
+          request_path.sub(%r{\A/}, '') # remove leading slash for relative URLs
+        else
+          api_url + request_path
+        end
+      end
     end
   end
 end

data/lib/europeana/api/resource.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+module Europeana
+  module API
+    ##
+    # Module for resources retrieved from the Europeana API
+    module Resource
+      extend ActiveSupport::Concern
+
+      included do
+        class_attribute :api_endpoints
+      end
+
+      class_methods do
+        # @todo path is not optional; ensure that it exists
+        def has_api_endpoint(name, **options)
+          self.api_endpoints ||= {}
+          self.api_endpoints[name] = options
+
+          define_singleton_method(name) do |params = {}, &block|
+            api_request_for_endpoint(name, params).execute(&block)
+          end
+        end
+
+        def api_request_for_endpoint(name, params = {})
+          Request.new(self.api_endpoints[name], params)
+        end
+      end
+    end
+  end
+end

data/lib/europeana/api/response.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+module Europeana
+  module API
+    class Response
+      attr_reader :faraday_response, :request, :error_message
+
+      delegate :body, :headers, :status, to: :faraday_response
+      delegate :endpoint, to: :request
+
+      # @param request [Europeana::API::Request]
+      # @param faraday_response [Faraday::Response]
+      def initialize(request, faraday_response)
+        @request = request
+        @faraday_response = faraday_response
+        @error_message = detect_error_message
+      end
+
+      def validate!
+        return if body.is_a?(Hash) && body[:success]
+        validate_endpoint_errors!
+        validate_generic_errors!
+      end
+
+      def validate_endpoint_errors!
+        (endpoint[:errors] || {}).each_pair do |error_pattern, exception_class|
+          fail exception_class.new(faraday_response), error_message if error_message =~ Regexp.new(error_pattern)
+        end
+      end
+
+      def validate_generic_errors!
+        fail Errors::ResourceNotFoundError.new(faraday_response), error_message if status == 404
+        fail Errors::MissingAPIKeyError.new(faraday_response), error_message if status == 403 && error_message =~ /No API key/
+        fail Errors::ClientError.new(faraday_response), error_message if (400..499).cover?(status)
+        fail Errors::ServerError.new(faraday_response), error_message if (500..599).cover?(status)
+      end
+
+      def detect_error_message
+        return nil unless (400..599).cover?(status)
+        if body.is_a?(Hash) && body.key?(:error)
+          body[:error]
+        else
+          Rack::Utils::HTTP_STATUS_CODES[status]
+        end
+      end
+    end
+  end
+end

data/lib/europeana/api/version.rb

@@ -1,7 +1,8 @@
+# frozen_string_literal: true
 module Europeana
   ##
   # Sets the *gem* version (not the *API* version)
   module API
-    VERSION = '0.5.2'
+    VERSION = '1.0.0'
   end
 end

data/spec/europeana/api/annotation_spec.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+RSpec.describe Europeana::API::Annotation do
+  it_behaves_like 'a resource with API endpoint', :fetch, :get
+  it_behaves_like 'a resource with API endpoint', :search, :get
+  it_behaves_like 'a resource with API endpoint', :create, :post
+  it_behaves_like 'a resource with API endpoint', :update, :put
+  it_behaves_like 'a resource with API endpoint', :delete, :delete
+
+  before(:all) do
+    Europeana::API.configure do |config|
+      config.parse_json_to = OpenStruct
+    end
+  end
+
+  after(:all) do
+    Europeana::API.configure do |config|
+      config.parse_json_to = Hash
+    end
+  end
+
+  describe '.fetch' do
+    before do
+      stub_request(:get, %r{://www.europeana.eu/api/annotations/abc/123}).
+        to_return(status: 200,
+                  body: '{"@context":"https://www.w3.org/ns/anno.jsonld", "body":"Sheet music"}',
+                  headers: { 'Content-Type' => 'application/ld+json' })
+    end
+
+    it 'requests an annotation from the API' do
+      described_class.fetch(provider: 'abc', id: '123')
+      expect(a_request(:get, %r{www.europeana.eu/api/annotations/abc/123})).to have_been_made.once
+    end
+
+    it 'returns the body of the response' do
+      record = described_class.fetch(provider: 'abc', id: '123')
+      expect(record).to be_an(OpenStruct)
+      expect(record).to respond_to(:body)
+    end
+  end
+
+  describe '.search' do
+    before do
+      stub_request(:get, %r{://www.europeana.eu/api/annotations/search}).
+        to_return(status: 200,
+                  body: '{"@context": "https://www.w3.org/ns/anno.jsonld", "items":[]}',
+                  headers: { 'Content-Type' => 'application/ld+json' })
+    end
+
+    it 'requests an annotation search from the API' do
+      described_class.search(query: '*:*')
+      expect(a_request(:get, %r{www.europeana.eu/api/annotations/search})).to have_been_made.once
+    end
+
+    it 'returns the body of the response' do
+      results = described_class.search(query: '*:*')
+      expect(results).to be_an(OpenStruct)
+      expect(results).to respond_to(:items)
+    end
+  end
+
+  describe '.delete' do
+    before do
+      stub_request(:delete, %r{://www.europeana.eu/api/annotations/abc/123}).
+        to_return(status: 204, body: '')
+    end
+
+    it 'deletes an annotation from the API' do
+      described_class.delete(provider: 'abc', id: '123')
+      expect(a_request(:delete, %r{www.europeana.eu/api/annotations/abc/123})).to have_been_made.once
+    end
+
+    it 'returns the empty body of the response' do
+      record = described_class.delete(provider: 'abc', id: '123')
+      expect(record).to eq('')
+    end
+  end
+end

data/spec/europeana/api/client_spec.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+RSpec.describe Europeana::API::Client do
+  it { should delegate_method(:get).to(:connection) }
+  it { should delegate_method(:post).to(:connection) }
+
+  describe '.get' do
+    context 'without URL' do
+      it 'makes a request to the root API URL' do
+        stub_request(:get, Regexp.new(Europeana::API.url))
+        subject.get
+        expect(a_request(:get, Regexp.new(Europeana::API.url))).to have_been_made.once
+      end
+    end
+
+    context 'with URL' do
+      context 'with GET method' do
+        it 'sends an HTTP GET request to it' do
+          url = 'http://www.example.com/'
+          stub_request(:get, Regexp.new(url))
+          subject.get(url)
+          expect(a_request(:get, Regexp.new(url))).to have_been_made.once
+        end
+      end
+
+      context 'when request fails' do
+        it 'retries up to 5 times' do
+          url = 'http://www.example.com/'
+          stub_request(:get, Regexp.new(url)).to_raise(Errno::ECONNREFUSED).times(3).to_return(body: 'OK')
+
+          subject.get(url)
+          expect(a_request(:get, Regexp.new(url))).to have_been_made.times(4)
+        end
+      end
+
+      context 'when request times out' do
+        it 'does NOT retry' do
+          url = 'http://www.example.com/'
+          stub_request(:get, Regexp.new(url)).to_timeout.times(3).to_return(body: 'OK')
+
+          expect { subject.get(url) }.to raise_error(Faraday::TimeoutError)
+          expect(a_request(:get, Regexp.new(url))).to have_been_made.times(1)
+        end
+      end
+    end
+  end
+end

data/spec/europeana/api/entity_spec.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+RSpec.describe Europeana::API::Entity do
+  it_behaves_like 'a resource with API endpoint', :resolve
+  it_behaves_like 'a resource with API endpoint', :fetch
+  it_behaves_like 'a resource with API endpoint', :suggest
+end

data/spec/europeana/api/faraday_middleware/request/authenticated_request_spec.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+RSpec.describe Europeana::API::FaradayMiddleware::AuthenticatedRequest do
+  context 'with `Europeana::API.api_key` set' do
+    context 'without `wskey` param' do
+      it 'uses `Europeana::API.api_key`'
+    end
+
+    context 'with `wskey` param' do
+      it 'uses `wskey` param'
+    end
+  end
+
+  context 'without `Europeana::API.api_key` set' do
+    context 'without `wskey` param' do
+      it 'fails'
+    end
+
+    context 'with `wskey` param' do
+      it 'uses `wskey` param'
+    end
+  end
+end

data/spec/europeana/api/queue_spec.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+RSpec.describe Europeana::API::Queue do
+  it 'handles parallel requests to the API'
+end

data/spec/europeana/api/record_spec.rb

@@ -1,133 +1,83 @@
+# frozen_string_literal: true
 RSpec.describe Europeana::API::Record do
-  let(:api_key) { 'xyz' }
-  let(:record_id) { '/abc/1234' }
-  let(:params) { { callback: 'doSomething();' } }
-
-  before do
-    Europeana::API.api_key = api_key
-  end
-
-  describe '#new' do
-    context 'without record ID' do
-      it 'raises error' do
-        expect { subject }.to raise_error(ArgumentError)
-      end
-    end
-
-    context 'with record ID' do
-      context 'without params' do
-        subject { described_class.new(record_id) }
-
-        it 'should not raise error' do
-          expect { subject }.to_not raise_error
-        end
-
-        it 'sets id attribute' do
-          expect(subject.instance_variable_get(:@id)).to eq(record_id)
-        end
-      end
-
-      context 'with params' do
-        subject { described_class.new(record_id, params) }
-
-        it 'should not raise error' do
-          expect { subject }.to_not raise_error
-        end
-
-        it 'sets params attribute' do
-          expect(subject.instance_variable_get(:@params)).to eq(HashWithIndifferentAccess.new(params))
-        end
-      end
+  it_behaves_like 'a resource with API endpoint', :fetch
+  it_behaves_like 'a resource with API endpoint', :search
+  it_behaves_like 'a resource with API endpoint', :self
+  it_behaves_like 'a resource with API endpoint', :parent
+  it_behaves_like 'a resource with API endpoint', :children
+  it_behaves_like 'a resource with API endpoint', :following_siblings
+  it_behaves_like 'a resource with API endpoint', :preceding_siblings
+  it_behaves_like 'a resource with API endpoint', :ancestor_self_siblings
+
+  before(:all) do
+    Europeana::API.configure do |config|
+      config.parse_json_to = OpenStruct
     end
   end
 
-  describe '#id' do
-    subject { described_class.new(record_id) }
-    it 'gets id attribute' do
-      expect(subject.id).to eq(subject.instance_variable_get(:@id))
+  after(:all) do
+    Europeana::API.configure do |config|
+      config.parse_json_to = Hash
     end
   end
 
-  describe '#id=' do
-    subject { described_class.new(record_id) }
-
-    context 'with valid ID' do
-      it 'sets id attribute' do
-        subject.id = '/xyz/5678'
-        expect(subject.instance_variable_get(:@id)).to eq('/xyz/5678')
-      end
+  describe '.fetch' do
+    before do
+      stub_request(:get, %r{://www\.europeana\.eu/api/v2/record/abc/123\.json}).
+        to_return(status: 200, body: '{"success":true, "object":{}}', headers: { 'Content-Type' => 'application/json' })
     end
 
-    context 'invalid ID' do
-      it 'raises error' do
-        expect { subject.id = 'invalid' }.to raise_error('Invalid Europeana record ID: "invalid"')
-      end
+    it 'requests a record from the API' do
+      described_class.fetch(id: '/abc/123')
+      expect(a_request(:get, %r{www\.europeana\.eu/api/v2/record/abc/123\.json})).to have_been_made.once
     end
-  end
 
-  describe '#params' do
-    subject { described_class.new(record_id, params) }
-    it 'gets params attribute' do
-      expect(subject.params).to eq(subject.instance_variable_get(:@params))
+    it 'returns the body of the response' do
+      record = described_class.fetch(id: '/abc/123')
+      expect(record).to be_an(OpenStruct)
+      expect(record).to respond_to(:object)
     end
   end
 
-  describe '#params=' do
-    subject { described_class.new(record_id, {}) }
+  describe '.search' do
+    before do
+      stub_request(:get, %r{://www\.europeana\.eu/api/v2/search\.json}).
+        to_return(status: 200, body: '{"success":true, "items":[]}', headers: { 'Content-Type' => 'application/json' })
+    end
 
-    context 'valid params' do
-      it 'sets params attribute' do
-        subject.params = params
-        expect(subject.instance_variable_get(:@params)).to eq(params)
-      end
+    it 'requests a record search from the API' do
+      described_class.search(query: '*:*')
+      expect(a_request(:get, %r{www\.europeana\.eu/api/v2/search\.json\?query=*:*})).to have_been_made.once
     end
 
-    it 'validates param names' do
-      expect { subject.params = { invalid: 'parameter' } }.to raise_error(/Unknown key: :?invalid/)
+    it 'returns the body of the response' do
+      results = described_class.search(query: '*:*')
+      expect(results).to be_an(OpenStruct)
+      expect(results).to respond_to(:items)
     end
   end
 
-  describe '#params_with_authentication' do
-    subject { described_class.new(record_id, params) }
-
-    context 'with API key' do
-      it 'adds API key to params' do
-        expect(subject.params_with_authentication).to eq(HashWithIndifferentAccess.new(params).merge(wskey: api_key))
+  %w(self parent children preceding_siblings following_siblings ancestor_self_siblings).each do |endpoint|
+    describe ".#{endpoint}" do
+      before do
+        stub_request(:get, %r{://www\.europeana\.eu/api/v2/record/abc/123/#{endpoint.to_s.dasherize}\.json}).
+          to_return(status: 200, body: %({"success":true, "#{endpoint.to_s.dasherize}":[]}), headers: { 'Content-Type' => 'application/json' })
       end
-    end
 
-    context 'without API key' do
-      it 'raises an error' do
-        Europeana::API.api_key = nil
-        expect { subject.params_with_authentication }.to raise_error(Europeana::API::Errors::MissingAPIKeyError)
+      it "requests a record's #{endpoint.to_s.humanize.downcase} from the API" do
+        described_class.send(endpoint, id: '/abc/123')
+        expect(a_request(:get, %r{www\.europeana\.eu/api/v2/record/abc/123/#{endpoint.to_s.dasherize}\.json})).to have_been_made.once
       end
-    end
-  end
-
-  describe '#request_uri' do
-    subject { described_class.new(record_id, params) }
 
-    it 'returns a URI' do
-      expect(subject.request_uri).to be_a(URI)
-    end
-
-    it 'includes the record ID' do
-      expect(subject.request_uri.to_s).to include(record_id)
-    end
-
-    it 'includes the query params' do
-      expect(subject.request_uri.to_s).to include(params.to_query)
+      it 'returns the body of the response' do
+        results = described_class.send(endpoint, id: '/abc/123')
+        expect(results).to be_an(OpenStruct)
+        expect(results).to respond_to(endpoint)
+      end
     end
   end
 
-  describe '#get' do
-    subject { described_class.new(record_id, params).get }
-    it_behaves_like 'record request'
-  end
-
-  describe '#hierarchy' do
-    let(:record) { described_class.new(record_id, params) }
-    subject { record.hierarchy }
-    it { is_expected.to be_a(Europeana::API::Record::Hierarchy) }
+  describe '.escape' do
+    it 'escapes Lucene characters'
   end
 end