europeana-api 0.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 894ad987b215b9e7dfd6002f1e2f7225fcab25ae
+  data.tar.gz: 87e594f04c09dc273d7b285975ae682b4fbf7675
+SHA512:
+  metadata.gz: bcd7ad50a881202448ef74db5ab0165b5147448ab6a1e2df915741dd53d27cc76e723c5270a22de4778b06641d21dba5f634553d4e16f8457fe4e3c0afe08d8c
+  data.tar.gz: c490cbfa7b307dd0a25ba8cd84d4226b2bc49b8efb461bec3c975e38b6822cdfa337df5fc88fbe56543aea7d5cbf28c7408d6594b5c6c6f9bb4625fd96c0dd1c

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in europeana.gemspec
+gemspec

data/README.md

@@ -0,0 +1,57 @@
+# Europeana
+
+Ruby client library for the search and retrieval of records from the [Europeana
+REST API](http://labs.europeana.eu/api/introduction/).
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'europeana-api'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install europeana-api
+
+## Usage
+
+### Authentication
+
+Authentication is *required* for all requests to the Europeana API.
+
+Only Basic Authentication (by API key) is supported. 
+
+Sign up for an API key at: http://labs.europeana.eu/api/registration/
+
+Configure your application with the API key:
+
+    Europeana::API.api_key = "xyz"
+
+### Search
+
+    search = Europeana::API.search(:query => '"first world war"') # => { "success" => true, "items" => [ ... ], "totalResults" => 1234, ... }
+    search["items"] # => [ item1, item2, ... ]
+    search["totalResults"] # => 1234
+    
+See http://labs.europeana.eu/api/search/ for details of the data returned in
+the search response.
+
+### Record
+
+    record = Europeana::API.record("abc/1234") # => { "success" => true, "object" => { ... }, ... }
+    record["object"] # => { "title" => "...", "proxies" => [ ... ], "aggregations" => [ ... ]
+
+See http://labs.europeana.eu/api/record/ for details of the data returned in
+the record response.
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1 @@
+require 'bundler/gem_tasks'

data/europeana-api.gemspec

@@ -0,0 +1,28 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'europeana/api/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'europeana-api'
+  spec.version       = Europeana::API::VERSION
+  spec.authors       = ['Richard Doe']
+  spec.email         = ['richard.doe@rwdit.net']
+  spec.description   = 'Search and retrieve records from the Europeana REST API'
+  spec.summary       = 'Ruby client library for the Europeana API'
+  spec.homepage      = 'https://github.com/rwd/europeana-api-client-ruby'
+  spec.license       = 'EUPL 1.1'
+
+  spec.files         = `git ls-files`.split($RS)
+  spec.executables   = spec.files.grep(/^bin\//) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(/^(test|spec|features)\//)
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'activesupport', '>= 3.0'
+  spec.add_dependency 'multi_json', '~> 1.0'
+
+  spec.add_development_dependency 'bundler', '~> 1.3'
+  spec.add_development_dependency 'rake'
+  spec.add_development_dependency 'rspec', '~> 3.0'
+  spec.add_development_dependency 'webmock', '~> 1.18.0'
+end

data/lib/europeana/api.rb

@@ -0,0 +1,95 @@
+require 'europeana/api/version'
+require 'uri'
+require 'logger'
+require 'active_support/core_ext/object'
+require 'active_support/hash_with_indifferent_access'
+
+##
+# Europeana REST API client
+module Europeana
+  module API
+    API_VERSION = 'v2'
+    URL = "http://www.europeana.eu/api/#{API_VERSION}"
+
+    autoload :Errors,   'europeana/api/errors'
+    autoload :Record,   'europeana/api/record'
+    autoload :Request,  'europeana/api/request'
+    autoload :Search,   'europeana/api/search'
+
+    class << self
+      # The Europeana API key, required for authentication
+      attr_accessor :api_key
+
+      ##
+      # The maximum number of retries permitted
+      #
+      # Retries occur when a network request to the API fails. The default is 5
+      # retries before giving up.
+      #
+      # @return [Integer]
+      #
+      attr_accessor :max_retries
+
+      ##
+      # The number of seconds to wait between retries
+      #
+      # The default is 10 seconds.
+      #
+      # @return [Integer]
+      #
+      attr_accessor :retry_delay
+
+      ##
+      # Sets configuration values to their defaults
+      #
+      def defaults!
+        self.max_retries = 5
+        self.retry_delay = 10
+      end
+
+      ##
+      # Sends a Search request to the Europeana API
+      #
+      # Equivalent to:
+      #   search = Europeana::Search.new(params)
+      #   search.execute
+      #
+      # @param [Hash] params Query parameters
+      # @return [Hash] search response
+      # @see Europeana::Search#execute
+      #
+      def search(params = {})
+        Search.new(params).execute
+      end
+
+      ##
+      # Sends a Record request to the Europeana API
+      #
+      # Equivalent to:
+      #   search = Europeana::Record.new(record_id, params)
+      #   record.get
+      #
+      # @param [String] Record ID
+      # @param [Hash] params Query parameters
+      # @return [Hash] search response
+      # @see Europeana::Record#get
+      #
+      def record(record_id, params = {})
+        Record.new(record_id, params).get
+      end
+
+      def logger
+        unless @logger
+          if defined?(Rails) && Rails.logger
+            @logger = Rails.logger
+          else
+            @logger = Logger.new(STDOUT)
+          end
+        end
+        @logger
+      end
+    end
+
+    self.defaults!
+  end
+end

data/lib/europeana/api/errors.rb

@@ -0,0 +1,51 @@
+module Europeana
+  module API
+    module Errors
+      ##
+      # Raised if API requests are attempted without the API key having been set.
+      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:
+
+    Europeana.api_key = "xyz"
+          MSG
+          super(msg)
+        end
+      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
+      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
+      end
+    end
+  end
+end

data/lib/europeana/api/record.rb

@@ -0,0 +1,142 @@
+module Europeana
+  module API
+    ##
+    # Interface to the Europeana API Record method
+    #
+    # @see http://labs.europeana.eu/api/record/
+    class Record
+      # Europeana ID of the record
+      attr_accessor :id
+
+      # Request parameters to send to the API
+      attr_accessor :params
+
+      ##
+      # @param [String] id Europeana ID of the record
+      # @param [Hash] params Request parameters
+      def initialize(id, params = {})
+        self.id = id
+        self.params = params
+        @hierarchy = HashWithIndifferentAccess.new
+      end
+
+      ##
+      # Returns query params with API key added
+      #
+      # @return [Hash]
+      def params_with_authentication
+        return params if params.key?(:wskey)
+        unless Europeana::API.api_key.present?
+          fail Errors::MissingAPIKeyError
+        end
+        params.merge(wskey: Europeana::API.api_key)
+      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 URI for this Record request with parameters
+      #
+      # @return [URI]
+      def request_uri
+        uri = URI.parse(Europeana::API::URL + "/record#{@id}.json")
+        uri.query = params_with_authentication.to_query
+        uri
+      end
+
+      ##
+      # Sends a request for this record to the API
+      #
+      # @return [HashWithIndifferentAccess]
+      # @raise [Europeana::Errors::ResponseError] if API response could not be
+      #   parsed as JSON
+      # @raise [Europeana::Errors::RequestError] if API response has
+      #   `success:false`
+      # @raise [Europeana::Errors::RequestError] if API response has 404 status
+      #   code
+      def get
+        request = Request.new(request_uri)
+        response = request.execute
+        body = JSON.parse(response.body)
+        fail Errors::RequestError, body['error'] unless body['success']
+        HashWithIndifferentAccess.new(body)
+      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 Errors::ResponseError
+        end
+      end
+
+      ##
+      # Gets hierarchy data about this and related records from
+      # ancestor-self-siblings.json API method
+      #
+      # @note Proof of concept implementation for demo purposes.
+      # @todo Refactor if functionality to be retained.
+      def hierarchy(*args)
+        args = [:self] if args.blank?
+
+        data = {}
+        args.each do |method|
+          unless @hierarchy.key?(method)
+            @hierarchy[method] = hierarchical_data(method).select do |_k, v|
+              v.is_a?(Enumerable)
+            end
+          end
+          data.merge!(@hierarchy[method])
+        end
+        data
+      end
+
+      def hierarchical_data(method = :self)
+        request = Request.new(hierarchical_data_uri(method))
+        response = request.execute
+        body = JSON.parse(response.body)
+        fail Errors::RequestError, body['message'] unless body['success']
+        body
+      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 Errors::ResponseError
+        end
+      end
+
+      def hierarchical_data_uri(method = :self)
+        uri = URI.parse(Europeana::API::URL + "/record#{@id}/#{method}.json")
+        uri.query = params_with_authentication.to_query
+        uri
+      end
+    end
+  end
+end

data/lib/europeana/api/request.rb

@@ -0,0 +1,49 @@
+require 'active_support/benchmarkable'
+require 'net/http'
+
+module Europeana
+  module API
+    ##
+    # Europeana 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
+        logger.debug("#{self.class} API URL: #{uri}")
+
+        benchmark("#{self.class} API query", level: :debug) do
+          http = Net::HTTP.new(uri.host, uri.port)
+          request = Net::HTTP::Get.new(uri.request_uri)
+          retries = Europeana::API.max_retries
+
+          begin
+            @response = http.request(request)
+          rescue Timeout::Error, Errno::ECONNREFUSED, EOFError
+            retries -= 1
+            raise unless retries > 0
+            sleep Europeana::API.retry_delay
+            retry
+          end
+
+          @response
+        end
+      end
+
+      def logger
+        Europeana::API.logger
+      end
+    end
+  end
+end

data/lib/europeana/api/search.rb

@@ -0,0 +1,67 @@
+module Europeana
+  module API
+    ##
+    # Interface to Europeana API's Search method
+    class Search
+      # Query params
+      attr_accessor :params
+
+      ##
+      # @param [Hash] params Europeana API request parameters for Search query
+      def initialize(params = {})
+        @params = HashWithIndifferentAccess.new(params)
+      end
+
+      ##
+      # Sends the Search request to the API
+      #
+      # @return [HashWithIndifferentAccess]
+      # @raise [Europeana::Errors::ResponseError] if API response could not be
+      #   parsed as JSON
+      # @raise [Europeana::Errors::RequestError] if API response has
+      #   `success:false`
+      def execute
+        request = Request.new(request_uri)
+        response = request.execute
+        body = JSON.parse(response.body)
+        fail Errors::RequestError, body['error'] unless body['success']
+        HashWithIndifferentAccess.new(body)
+      rescue JSON::ParserError
+        raise Errors::ResponseError
+      end
+
+      ##
+      # Returns query params with API key added
+      #
+      # @return [Hash]
+      def params_with_authentication
+        return params if params.key?(:wskey)
+        unless Europeana::API.api_key.present?
+          fail Errors::MissingAPIKeyError
+        end
+        params.merge(wskey: Europeana::API.api_key)
+      end
+
+      ##
+      # Gets the URI for this Search request with parameters
+      #
+      # @return [URI]
+      def request_uri
+        uri = URI.parse(Europeana::API::URL + '/search.json')
+        uri.query = request_uri_query
+        uri
+      end
+
+      def request_uri_query
+        uri_query = ''
+        params_with_authentication.each_pair do |name, value|
+          [value].flatten.each do |v|
+            uri_query << '&' unless uri_query.blank?
+            uri_query << CGI.escape(name.to_s) + '=' + CGI.escape(v.to_s)
+          end
+        end
+        uri_query
+      end
+    end
+  end
+end

data/lib/europeana/api/version.rb

@@ -0,0 +1,7 @@
+module Europeana
+  ##
+  # Sets the *gem* version (not the *API* version)
+  module API
+    VERSION = '0.3.0'
+  end
+end

data/spec/europeana/errors_spec.rb

@@ -0,0 +1,13 @@
+require 'spec_helper'
+
+module Europeana
+  describe "Errors" do
+    describe "MissingAPIKeyError" do
+      subject { Europeana::Errors::MissingAPIKeyError.new }
+      
+      it "has an informative message" do
+        expect(subject.message).to match("Missing API key.")
+      end
+    end
+  end
+end

data/spec/europeana/record_spec.rb

@@ -0,0 +1,132 @@
+require 'spec_helper'
+
+module Europeana
+  describe Record do
+    before(:each) do
+      @api_key = "xyz"
+      Europeana.api_key = @api_key
+      @record_id = "/abc/1234"
+      @params = { :callback => "doSomething();" }
+    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 { Europeana::Record.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 { Europeana::Record.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(@params)
+          end
+        end
+      end
+    end
+    
+    describe "#id" do
+      subject { Europeana::Record.new(@record_id) }
+      it "gets id attribute" do
+        expect(subject.id).to eq(subject.instance_variable_get(:@id))
+      end
+    end
+    
+    describe "#id=" do
+      subject { Europeana::Record.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
+      end
+      
+      context "invalid ID" do
+        it "raises error" do
+          expect { subject.id = "invalid" }.to raise_error("Invalid Europeana record ID.")
+          
+        end
+      end
+        
+    end
+    
+    describe "#params" do
+      subject { Europeana::Record.new(@record_id, @params) }
+      it "gets params attribute" do
+        expect(subject.params).to eq(subject.instance_variable_get(:@params))
+      end
+    end
+    
+    describe "#params=" do
+      subject { Europeana::Record.new(@record_id, {}) }
+      
+      context "valid params" do
+        it "sets params attribute" do
+          subject.params = @params
+          expect(subject.instance_variable_get(:@params)).to eq(@params)
+        end
+      end
+      
+      it "validates param names" do
+        expect { subject.params = { :invalid => "parameter" } }.to raise_error(/Unknown key: :?invalid/)
+      end
+    end
+    
+    describe "#params_with_authentication" do
+      subject { Europeana::Record.new(@record_id, @params) }
+      
+      context "with API key" do
+        it "adds API key to params" do
+          expect(subject.params_with_authentication).to eq(@params.merge(:wskey => @api_key))
+        end
+      end
+      
+      context "without API key" do
+        it "raises an error" do
+          Europeana.api_key = nil
+          expect { subject.params_with_authentication }.to raise_error(Europeana::Errors::MissingAPIKeyError)
+        end
+      end
+    end
+    
+    describe "#request_uri" do
+      subject { Europeana::Record.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)
+      end
+    end
+    
+    describe "#get" do
+      subject { Europeana::Record.new(@record_id, @params).get }
+      it_behaves_like "record request"
+    end
+  end
+end

data/spec/europeana/search_spec.rb

@@ -0,0 +1,92 @@
+require 'spec_helper'
+
+module Europeana
+  describe Search do
+    before(:all) do
+      @params = { :query => "test", :profile => "standard", :qf => "where:London", :rows => 100, :start => 1, :callback => "" }
+      @api_key = "xyz"
+    end
+    
+    before(:each) do
+      Europeana.api_key = @api_key
+    end
+    
+    describe "#new" do
+      context "with no API request params" do
+        subject { lambda { Europeana::Search.new } }
+        it { should_not raise_error }
+      end
+      
+      context "with API request params" do
+        subject { Europeana::Search.new(@params) }
+        it "should not raise error" do
+          expect { subject }.not_to raise_error
+        end
+        it "stores the request params" do
+          expect(subject.instance_variable_get(:@params)).to eq(@params)
+        end
+      end
+    end
+    
+    describe "#params" do
+      subject { Europeana::Search.new(@params) }
+      it "gets params attribute" do
+        expect(subject.params).to eq(@params)
+      end
+    end
+    
+    describe "#params=" do
+      subject { Europeana::Search.new }
+      
+      context "valid params" do
+        it "sets params attribute" do
+          subject.params = @params
+          expect(subject.instance_variable_get(:@params)).to eq(@params)
+        end
+      end
+      
+      it "validates param names" do
+        expect { subject.params = { :invalid => "parameter" } }.to raise_error(/Unknown key: :?invalid/)
+      end
+    end
+    
+    describe "#request_uri" do
+      it "returns a URI" do
+        expect(subject.request_uri).to be_a(URI)
+      end
+      
+      it "includes request params" do
+        expect(subject.request_uri.to_s).to eq("http://www.europeana.eu/api/v2/search.json?query=&wskey=#{@api_key}")
+      end
+      
+      it "handles Hash of qf params" do
+        subject.params[:qf] = { :where => [ "London", "Paris" ], :what => "Photograph" }
+        expect(subject.request_uri.to_s).to eq("http://www.europeana.eu/api/v2/search.json?query=&wskey=#{@api_key}&qf=where:London&qf=where:Paris&qf=what:Photograph")
+      end
+    end
+    
+    describe "#params_with_authentication" do
+      subject { Europeana::Search.new }
+      
+      context "with API key" do
+        it "adds API key to params" do
+          subject.params = @params
+          expect(subject.params_with_authentication).to eq(@params.merge(:wskey => @api_key))
+        end
+      end
+      
+      context "without API key" do
+        it "raises an error" do
+          subject.params = @params
+          Europeana.api_key = nil
+          expect { subject.params_with_authentication }.to raise_error(Europeana::Errors::MissingAPIKeyError)
+        end
+      end
+    end
+    
+    describe "#execute" do
+      subject { Europeana::Search.new(@params).execute }
+      it_behaves_like "search request"
+    end
+  end
+end

data/spec/europeana_spec.rb

@@ -0,0 +1,81 @@
+require 'spec_helper'
+
+describe Europeana do
+  before(:each) do
+    Europeana.defaults!
+  end
+  
+  describe "::URL" do
+    it "returns 'http://www.europeana.eu/api/v2'" do
+      expect(Europeana::URL).to eq("http://www.europeana.eu/api/v2")
+    end
+  end
+  
+  describe ".api_key=" do
+    before(:all) do
+      @api_key = "xyz"
+    end
+    it "sets the API key" do
+      Europeana.api_key = @api_key
+      expect(Europeana.instance_variable_get(:@api_key)).to eq(@api_key)
+    end
+  end
+  
+  describe ".api_key" do
+    before(:all) do
+      @api_key = "xyz"
+    end
+    it "gets the API key" do
+      Europeana.instance_variable_set(:@api_key, @api_key)
+      expect(Europeana.api_key).to eq(@api_key)
+    end
+  end
+  
+  describe ".max_retries" do
+    it "defaults to 5" do
+      expect(Europeana.max_retries).to eq(5)
+    end
+  end
+  
+  describe ".max_retries=" do
+    it "sets the maximum number of retries" do
+      Europeana.max_retries = 2
+      expect(Europeana.max_retries).to eq(2)
+    end
+  end
+  
+  describe ".retry_delay" do
+    it "defaults to 10" do
+      expect(Europeana.retry_delay).to eq(10)
+    end
+  end
+  
+  describe ".retry_delay=" do
+    it "sets the retry delay" do
+      Europeana.retry_delay = 3
+      expect(Europeana.retry_delay).to eq(3)
+    end
+  end
+  
+  describe ".defaults!" do
+    it "sets retry delay to its default" do
+      Europeana.retry_delay = 3
+      expect { Europeana.defaults! }.to change { Europeana.retry_delay }.from(3).to(10)
+    end
+    
+    it "sets max retries to its default" do
+      Europeana.max_retries = 3
+      expect { Europeana.defaults! }.to change { Europeana.max_retries }.from(3).to(5)
+    end
+  end
+  
+  describe ".search" do
+    subject { Europeana.search(@params) }
+    it_behaves_like "search request"
+  end
+  
+  describe ".record" do
+    subject { Europeana.record(@record_id, @params) }
+    it_behaves_like "record request"
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,10 @@
+require 'europeana'
+require 'webmock/rspec'
+
+Dir["./spec/support/**/*.rb"].each { |f| require f }
+
+RSpec.configure do |config|
+  config.expect_with :rspec do |c|
+    c.syntax = :expect
+  end
+end

data/spec/support/shared_examples/api_request.rb

@@ -0,0 +1,56 @@
+shared_examples "API request" do
+  context "without API key" do
+    before(:each) do
+      Europeana.api_key = nil
+    end
+    
+    it "sends no HTTP request" do
+      begin
+        subject
+      rescue Europeana::Errors::MissingAPIKeyError
+      end
+      expect(a_request(:get, /www.europeana.eu\/api\/v2/)).not_to have_been_made
+    end
+  end
+  
+  context "with API key" do
+    before(:all) do
+      Europeana.api_key = "xyz"
+    end
+    
+    it "returns the response as a Hash" do
+      response = subject
+      expect(response).to be_a(Hash)
+    end
+    
+    context "when the API is unavailable" do
+      before(:each) do
+        Europeana.retry_delay = 0
+      end
+      
+      it "waits then retries" do
+        stub_request(:get, /www.europeana.eu\/api\/v2/).
+          to_timeout.times(1).then.
+          to_return(:body => '{"success":true}')
+        subject
+        expect(a_request(:get, /www.europeana.eu\/api\/v2/)).to have_been_made.times(2)
+      end
+    end
+    
+    context "when API response is unsuccessful" do
+      it "raises a RequestError" do
+        stub_request(:get, /www.europeana.eu\/api\/v2/).to_return(:body => '{"success":false,"error":"Something went wrong"}')
+        expect { subject }.to raise_error(Europeana::Errors::RequestError, "Something went wrong")
+      end
+    end
+    
+    context "when API response is invalid JSON" do
+      it "raises a ResponseError" do
+        stub_request(:get, /www.europeana.eu\/api\/v2/).to_return(:body => 'invalid JSON')
+        expect { subject }.to raise_error(Europeana::Errors::ResponseError)
+      end
+    end
+  end
+end
+
+

data/spec/support/shared_examples/record_request.rb

@@ -0,0 +1,32 @@
+shared_examples "record request" do
+  before(:all) do
+    @api_key = "xyz"
+    @record_id = "/abc/1234"
+    @params = { :callback => "doSomething();" }
+  end
+  
+  before(:each) do
+    stub_request(:get, /www.europeana.eu\/api\/v2\/record#{@record_id}\.json/).to_return(:body => '{"success":true}')
+  end
+  
+  it_behaves_like "API request"
+  
+  context "with API key" do
+    before(:all) do
+      Europeana.api_key = @api_key
+    end
+    
+    it "sends a Record request to the API" do
+      subject
+      expect(a_request(:get, /www.europeana.eu\/api\/v2\/record#{@record_id}\.json/)).to have_been_made.once
+    end
+    
+    context "when record ID is invalid" do
+      it "raises RequestError from HTML 404 response" do
+        stub_request(:get, /www.europeana.eu\/api\/v2\/record#{@record_id}\.json/).
+          to_return(:body => '<html></html>', :headers => { 'Content-Type' => 'text/html' }, :status => 404)
+        expect { subject }.to raise_error(Europeana::Errors::RequestError, "Invalid record identifier: #{@record_id}")
+      end
+    end
+  end
+end

data/spec/support/shared_examples/search_request.rb

@@ -0,0 +1,40 @@
+shared_examples "search request" do
+  before(:all) do
+    @api_key = "xyz"
+    @params = {}
+  end
+  
+  before(:each) do
+    stub_request(:get, /www.europeana.eu\/api\/v2\/search\.json/).to_return(:body => '{"success":true}')
+  end
+  
+  it_behaves_like "API request"
+  
+  context "with API key" do
+    before(:all) do
+      Europeana.api_key = @api_key
+    end
+    
+    it "sends a Search request to the API" do
+      subject
+      expect(a_request(:get, /www.europeana.eu\/api\/v2\/search\.json/)).to have_been_made.once
+    end
+    
+    context "without query" do
+      it "sets an empty query" do
+        subject
+        expect(a_request(:get, /www.europeana.eu\/api\/v2\/search\.json\?query=/)).to have_been_made.once
+      end
+    end
+    
+    context "with query" do
+      before(:all) do
+        @params = { :query => "test" }
+      end
+      it "sends query" do
+        subject
+        expect(a_request(:get, /www.europeana.eu\/api\/v2\/search\.json\?query=test/)).to have_been_made.once
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,156 @@
+--- !ruby/object:Gem::Specification
+name: europeana-api
+version: !ruby/object:Gem::Version
+  version: 0.3.0
+platform: ruby
+authors:
+- Richard Doe
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-03-18 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: multi_json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.18.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.18.0
+description: Search and retrieve records from the Europeana REST API
+email:
+- richard.doe@rwdit.net
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- Gemfile
+- LICENSE.pdf
+- README.md
+- Rakefile
+- europeana-api.gemspec
+- lib/europeana/api.rb
+- lib/europeana/api/errors.rb
+- lib/europeana/api/record.rb
+- lib/europeana/api/request.rb
+- lib/europeana/api/search.rb
+- lib/europeana/api/version.rb
+- spec/europeana/errors_spec.rb
+- spec/europeana/record_spec.rb
+- spec/europeana/search_spec.rb
+- spec/europeana_spec.rb
+- spec/spec_helper.rb
+- spec/support/shared_examples/api_request.rb
+- spec/support/shared_examples/record_request.rb
+- spec/support/shared_examples/search_request.rb
+homepage: https://github.com/rwd/europeana-api-client-ruby
+licenses:
+- EUPL 1.1
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.6
+signing_key: 
+specification_version: 4
+summary: Ruby client library for the Europeana API
+test_files:
+- spec/europeana/errors_spec.rb
+- spec/europeana/record_spec.rb
+- spec/europeana/search_spec.rb
+- spec/europeana_spec.rb
+- spec/spec_helper.rb
+- spec/support/shared_examples/api_request.rb
+- spec/support/shared_examples/record_request.rb
+- spec/support/shared_examples/search_request.rb