europeana-api 0.3.6 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1bc2819fe6fc5ae0932fc49cda0b1bff61d435c4
-  data.tar.gz: b3d90815c7c71abcf4f7a6105e6e91652e395622
+  metadata.gz: 11327d8d43595f2888b4d3f501875fd45894abe5
+  data.tar.gz: 80e3e9ff21ab54e2bedcf70d8245fc7b84b30f50
 SHA512:
-  metadata.gz: 0ad1cda878963ceb34f275bfd51aa04b17dfcf81892a3ddce8ff14e144f4e72dab2af5bf75e3d7344224e06e5113ba78bd4932b1753fba252c53ac24317aec84
-  data.tar.gz: 1463a36d3b7104a3afcd88de68ba4dbd89655df9bf80a65f9e9e96b6e0f8f15801361e048d98ead124b3bb9e3a9135bdba40852f015c0abf3d7a67c452811f1c
+  metadata.gz: ec133494538ec61c5a45a01d9fb975f635b58b30136a5dd48c5f7c4efd5a3d5545ef36a238873b8ebb16b087628354e630c9903e1fe014cddd856412a1e3f35a
+  data.tar.gz: ca2870267f8f896def561a84ff9b087f3d73463f516c7c34b2080b5ec7da513a18804288c07bcfc6956ac10c9cc5e08df521f7888ca7cc7d417c3f4da841962a

data/.ruby-style.yml

@@ -496,7 +496,7 @@ Metrics/CyclomaticComplexity:
 Metrics/LineLength:
   Description: Limit lines to 80 characters.
   StyleGuide: https://github.com/bbatsov/ruby-style-guide#80-character-limits
-  Enabled: true
+  Enabled: false
   Max: 80
   AllowURI: true
   URISchemes:

data/.travis.yml

@@ -1,6 +1,9 @@
 language: ruby
 rvm:
-  - 2.2.1
+  - 2.0.0
+  - 2.1.7
+  - 2.2.2
+  - 2.2.3
 notifications:
   email: false
 sudo: false

data/README.md

@@ -1,6 +1,6 @@
 # Europeana
 
-[![Build Status](https://travis-ci.org/rwd/europeana-api-client-ruby.svg?branch=master)](https://travis-ci.org/rwd/europeana-api-client-ruby) [![Coverage Status](https://coveralls.io/repos/rwd/europeana-api-client-ruby/badge.svg?branch=master&service=github)](https://coveralls.io/github/rwd/europeana-api-client-ruby?branch=master) [![security](https://hakiri.io/github/rwd/europeana-api-client-ruby/master.svg)](https://hakiri.io/github/rwd/europeana-api-client-ruby/master)
+[![Build Status](https://travis-ci.org/europeana/europeana-api-client-ruby.svg?branch=master)](https://travis-ci.org/europeana/europeana-api-client-ruby) [![Coverage Status](https://coveralls.io/repos/europeana/europeana-api-client-ruby/badge.svg?branch=master&service=github)](https://coveralls.io/github/europeana/europeana-api-client-ruby?branch=master) [![security](https://hakiri.io/github/europeana/europeana-api-client-ruby/master.svg)](https://hakiri.io/github/europeana/europeana-api-client-ruby/master) [![Dependency Status](https://gemnasium.com/europeana/europeana-api-client-ruby.svg)](https://gemnasium.com/europeana/europeana-api-client-ruby)
 
 Ruby client library for the search and retrieval of records from the [Europeana
 REST API](http://labs.europeana.eu/api/introduction/).
@@ -33,7 +33,7 @@ Or install it yourself as:
 
 Authentication is *required* for all requests to the Europeana API.
 
-Only Basic Authentication (by API key) is supported. 
+Only Basic Authentication (by API key) is supported.
 
 Sign up for an API key at: http://labs.europeana.eu/api/registration/
 
@@ -58,17 +58,9 @@ the search response.
 ### Record
 
 ```ruby
-record = Europeana::API.record('abc/1234') # => { "success" => true, "object" => { ... }, ... }
-record['object'] # => { "title" => "...", "proxies" => [ ... ], "aggregations" => [ ... ]
+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/europeana-api.gemspec

@@ -18,7 +18,7 @@ Gem::Specification.new do |spec|
   spec.test_files    = spec.files.grep(/^(test|spec|features)\//)
   spec.require_paths = ['lib']
 
-  spec.required_ruby_version = '>= 1.9.2'
+  spec.required_ruby_version = '>= 2.0.0'
 
   spec.add_dependency 'activesupport', '>= 3.0'
   spec.add_dependency 'multi_json', '~> 1.0'

data/lib/europeana/api.rb

@@ -1,5 +1,9 @@
+require 'active_support/cache'
 require 'active_support/core_ext/object'
+require 'active_support/core_ext/hash/indifferent_access'
+require 'active_support/core_ext/hash/slice'
 require 'active_support/hash_with_indifferent_access'
+require 'active_support/inflector/methods'
 require 'europeana/api/version'
 require 'logger'
 require 'uri'
@@ -8,10 +12,11 @@ module Europeana
   ##
   # Europeana REST API client
   module API
-    autoload :Errors,   'europeana/api/errors'
-    autoload :Record,   'europeana/api/record'
-    autoload :Request,  'europeana/api/request'
-    autoload :Search,   'europeana/api/search'
+    autoload :Errors, 'europeana/api/errors'
+    autoload :Record, 'europeana/api/record'
+    autoload :Request, 'europeana/api/request'
+    autoload :Requestable, 'europeana/api/requestable'
+    autoload :Search, 'europeana/api/search'
 
     class << self
       ##
@@ -46,12 +51,18 @@ module Europeana
       # @return [Logger]
       attr_writer :logger
 
+      attr_accessor :cache_store
+
+      attr_accessor :cache_expires_in
+
       ##
       # Sets configuration values to their defaults
       def defaults!
         self.url = 'http://www.europeana.eu/api/v2'
         self.max_retries = 5
         self.retry_delay = 10
+        self.cache_store = ActiveSupport::Cache::NullStore.new
+        self.cache_expires_in = 24.hours
       end
 
       ##

data/lib/europeana/api/record.rb

@@ -5,31 +5,22 @@ 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_accessor :id
+      attr_reader :id
 
       # Request parameters to send to the API
-      attr_accessor :params
+      attr_reader :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) && params[:wskey].present?
-        unless Europeana::API.api_key.present?
-          fail Errors::MissingAPIKeyError
-        end
-        params.merge(wskey: Europeana::API.api_key)
+        @id = id
+        @params = params
       end
 
       ##
@@ -60,92 +51,47 @@ module Europeana
       end
 
       ##
-      # Gets the URI for this Record request with parameters
+      # Gets the URL for this Record request
       #
       # @param [Hash{Symbol => Object}] options
       # @option options [Boolean] :ld (false)
       #   Request JSON-LD
-      # @return [URI]
-      def request_uri(options = {})
-        url = Europeana::API.url + "/record#{@id}.json"
-        url << 'ld' if options[:ld]
-        uri = URI.parse(url)
-        uri.query = params_with_authentication.to_query
-        uri
+      # @return [String]
+      def request_url(options = {})
+        options.assert_valid_keys(:ld)
+        (Europeana::API.url + "/record#{@id}.json").tap do |url|
+          url << 'ld' if options[:ld]
+        end
       end
 
+      alias_method :get, :execute_request
+
       ##
-      # Sends a request for this record to the API
+      # Examines the `success` and `error` fields of the response for failure
       #
-      # @param [Hash{Symbol => Object}] options
-      # @option options [Boolean] :ld (false)
-      #   Request JSON-LD
-      # @return [Hash]
-      # @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(options = {})
-        request = Request.new(request_uri(options))
-        response = request.execute
-        body = JSON.parse(response.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)
-        end
-        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
+      # @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)
           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
+          raise
         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
+      def hierarchy
+        @hierarchy ||= Hierarchy.new(id)
       end
     end
   end

data/lib/europeana/api/record/hierarchy.rb

@@ -0,0 +1,48 @@
+module Europeana
+  module API
+    class Record
+      ##
+      # Retrieve record hierarchies over the Europeana API
+      class Hierarchy
+        autoload :AncestorSelfSiblings, 'europeana/api/record/hierarchy/ancestor_self_siblings'
+        autoload :Base, 'europeana/api/record/hierarchy/base'
+        autoload :Children, 'europeana/api/record/hierarchy/children'
+        autoload :FollowingSiblings, 'europeana/api/record/hierarchy/following_siblings'
+        autoload :Parent, 'europeana/api/record/hierarchy/parent'
+        autoload :PrecedingSiblings, 'europeana/api/record/hierarchy/preceding_siblings'
+        autoload :Self, 'europeana/api/record/hierarchy/self'
+
+        def initialize(id)
+          @id = id
+        end
+
+        # bad idea having a method named self, but this is just a minimal
+        # helper class, so going with it for consistency with the API
+        def self(params = {})
+          Self.new(@id, params).execute_request
+        end
+
+        def parent(params = {})
+          Parent.new(@id, params).execute_request
+        end
+
+        def children(params = {})
+          Children.new(@id, params).execute_request
+        end
+
+        def preceding_siblings(params = {})
+          PrecedingSiblings.new(@id, params).execute_request
+        end
+        alias_method :preceeding_siblings, :preceding_siblings
+
+        def following_siblings(params = {})
+          FollowingSiblings.new(@id, params).execute_request
+        end
+
+        def ancestor_self_siblings(params = {})
+          AncestorSelfSiblings.new(@id, params).execute_request
+        end
+      end
+    end
+  end
+end

data/lib/europeana/api/record/hierarchy/ancestor_self_siblings.rb

@@ -0,0 +1,12 @@
+module Europeana
+  module API
+    class Record
+      class Hierarchy
+        ##
+        # Retrieve record full(ish) hierarchy data over the Europeana API
+        class AncestorSelfSiblings < Base
+        end
+      end
+    end
+  end
+end

data/lib/europeana/api/record/hierarchy/base.rb

@@ -0,0 +1,32 @@
+module Europeana
+  module API
+    class Record
+      class Hierarchy
+        ##
+        # Base class for common heirarchy API behaviour
+        class Base
+          include Requestable
+
+          attr_accessor :params
+
+          def initialize(id, params = {})
+            @id = id
+            @params = params
+          end
+
+          def parse_response(response, options = {})
+            super.slice(:self, :children, :parent, 'preceeding-siblings', 'following-siblings', 'ancestors')
+          end
+
+          def request_url(_options = {})
+            Europeana::API.url + "/record#{@id}/#{api_method}.json"
+          end
+
+          def api_method
+            self.class.to_s.demodulize.underscore.dasherize
+          end
+        end
+      end
+    end
+  end
+end

data/lib/europeana/api/record/hierarchy/children.rb

@@ -0,0 +1,12 @@
+module Europeana
+  module API
+    class Record
+      class Hierarchy
+        ##
+        # Retrieve record children hierarchy data over the Europeana API
+        class Children < Base
+        end
+      end
+    end
+  end
+end

data/lib/europeana/api/record/hierarchy/following_siblings.rb

@@ -0,0 +1,12 @@
+module Europeana
+  module API
+    class Record
+      class Hierarchy
+        ##
+        # Retrieve record following siblings hierarchy data over the Europeana API
+        class FollowingSiblings < Base
+        end
+      end
+    end
+  end
+end

data/lib/europeana/api/record/hierarchy/parent.rb

@@ -0,0 +1,12 @@
+module Europeana
+  module API
+    class Record
+      class Hierarchy
+        ##
+        # Retrieve record parent hierarchy data over the Europeana API
+        class Parent < Base
+        end
+      end
+    end
+  end
+end

data/lib/europeana/api/record/hierarchy/preceding_siblings.rb

@@ -0,0 +1,15 @@
+module Europeana
+  module API
+    class Record
+      class Hierarchy
+        ##
+        # Retrieve record preceding siblings hierarchy data over the Europeana API
+        class PrecedingSiblings < Base
+          def api_method
+            'preceeding-siblings' # mis-spelt on the API
+          end
+        end
+      end
+    end
+  end
+end

data/lib/europeana/api/record/hierarchy/self.rb

@@ -0,0 +1,12 @@
+module Europeana
+  module API
+    class Record
+      class Hierarchy
+        ##
+        # Retrieve record self hierarchy data over the Europeana API
+        class Self < Base
+        end
+      end
+    end
+  end
+end

data/lib/europeana/api/requestable.rb

@@ -0,0 +1,104 @@
+module Europeana
+  module API
+    ##
+    # Mixin for classes that need to make Europeana API requests
+    #
+    # Class needs to implement {#request_url}
+    module Requestable
+      ##
+      # Request-specific params, to be overriden in including class
+      #
+      # @return [Hash]
+      def params
+        {}
+      end
+
+      ##
+      # Query params with API key added
+      #
+      # @return [Hash]
+      def params_with_authentication
+        return params if params.key?(:wskey) && params[:wskey].present?
+        unless Europeana::API.api_key.present?
+          fail Europeana::API::Errors::MissingAPIKeyError
+        end
+        params.merge(wskey: Europeana::API.api_key)
+      end
+
+      ##
+      # Execute the API request
+      #
+      # @param options [Hash] Options sent on to {#request_uri} and {#parse_response}
+      # @return (see #parse_response)
+      # @raise [Europeana::Errors::ResponseError] if API response could not be
+      #   parsed as JSON
+      def execute_request(options = {})
+        uri = request_uri(options)
+        cache_response_body(uri) do
+          response = Request.new(uri).execute
+          parse_response(response, options)
+        end
+      rescue JSON::ParserError
+        raise Errors::ResponseError
+      end
+
+      def cache_key(uri)
+        "Europeana/API/#{uri}"
+      end
+
+      def cache_response_body(uri)
+        Europeana::API.cache_store.fetch(cache_key(uri), expires_in: Europeana::API.cache_expires_in) do
+          yield
+        end
+      end
+
+      ##
+      # Parses a JSON response from the API
+      #
+      # @param response (see Net::HTTP#request)
+      # @param options [Hash] Options used by including class's implementation
+      #   of this method
+      # @return [HashWithIndifferentAccess] Parsed body of API response
+      def parse_response(response, _options = {})
+        JSON.parse(response.body).with_indifferent_access
+      end
+
+      ##
+      # URI query param string
+      #
+      # @return [String]
+      def request_uri_query
+        ''.tap do |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
+        end
+      end
+
+      ##
+      # Gets the URI for this request, with any query parameters
+      #
+      # @param [Hash{Symbol => Object}] options passed to {#request_url}
+      # @return [String]
+      def request_uri(options = {})
+        URI.parse(request_url(options)).tap do |uri|
+          uri.query = request_uri_query
+        end
+      end
+
+      ##
+      # URL for the request, without query params
+      #
+      # To be implemented by the including class
+      #
+      # @param options [Hash] Options used by implementation
+      # @return [String] Request URL
+      def request_url(_options = {})
+        fail NotImplementedError, "Requestable class #{self.class} does not implement #request_url"
+      end
+    end
+  end
+end

data/lib/europeana/api/search.rb

@@ -1,5 +1,3 @@
-require 'active_support/core_ext/hash'
-
 module Europeana
   module API
     ##
@@ -7,6 +5,8 @@ module Europeana
     class Search
       autoload :Fields, 'europeana/api/search/fields'
 
+      include Requestable
+
       # Query params
       attr_accessor :params
 
@@ -17,6 +17,7 @@ module Europeana
         # @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
@@ -31,56 +32,27 @@ module Europeana
       end
 
       ##
-      # Sends the Search request to the API
+      # Base URL for a Search request
       #
-      # @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)
-        unless body['success']
-          fail Errors::RequestError, (body.key?('error') ? body['error'] : response.code)
-        end
-        HashWithIndifferentAccess.new(body)
-      rescue JSON::ParserError
-        raise Errors::ResponseError
+      # @return [URI]
+      def request_url(_options = {})
+        Europeana::API.url + '/search.json'
       end
 
-      ##
-      # Returns query params with API key added
-      #
-      # @return [Hash]
-      def params_with_authentication
-        return params if params.key?(:wskey) && params[:wskey].present?
-        unless Europeana::API.api_key.present?
-          fail Errors::MissingAPIKeyError
-        end
-        params.merge(wskey: Europeana::API.api_key)
-      end
+      alias_method :execute, :execute_request
 
       ##
-      # Gets the URI for this Search request with parameters
+      # Examines the `success` and `error` fields of the response for failure
       #
-      # @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)
+      # @raise [Europeana::Errors::RequestError] if API response has
+      #   `success:false`
+      # @see Requestable#parse_response
+      def parse_response(response, _options = {})
+        super.tap do |body|
+          unless body[:success]
+            fail Errors::RequestError, (body.key?(:error) ? body[:error] : response.code)
           end
         end
-        uri_query
       end
     end
   end

data/lib/europeana/api/version.rb

@@ -2,6 +2,6 @@ module Europeana
   ##
   # Sets the *gem* version (not the *API* version)
   module API
-    VERSION = '0.3.6'
+    VERSION = '0.4.1'
   end
 end

data/spec/europeana/api/record/hierarchy_spec.rb

@@ -0,0 +1,15 @@
+RSpec.describe Europeana::API::Record::Hierarchy do
+  let(:record_id) { '/abc/1234' }
+  let(:params) { { callback: 'doSomething();' } }
+
+  subject { described_class.new(record_id) }
+
+  %w(self parent children).each do |relation|
+    describe "##{relation}" do
+      it "should retrieve #{relation} hierarchy data from the API" do
+        subject.send(relation)
+        expect(a_request(:get, %r{www.europeana.eu/api/v2/record#{record_id}/#{relation}.json})).to have_been_made.once
+      end
+    end
+  end
+end

data/spec/europeana/api/record_spec.rb

@@ -1,133 +1,133 @@
-require 'spec_helper'
+RSpec.describe Europeana::API::Record do
+  let(:api_key) { 'xyz' }
+  let(:record_id) { '/abc/1234' }
+  let(:params) { { callback: 'doSomething();' } }
 
-module Europeana
-  module API
-    describe Record do
-      let(:api_key) { 'xyz' }
-      let(:record_id) { '/abc/1234' }
-      let(:params) { { callback: 'doSomething();' } }
+  before do
+    Europeana::API.api_key = api_key
+  end
 
-      before do
-        Europeana::API.api_key = api_key
+  describe '#new' do
+    context 'without record ID' do
+      it 'raises error' do
+        expect { subject }.to raise_error(ArgumentError)
       end
+    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
+    context 'with record ID' do
+      context 'without params' do
+        subject { described_class.new(record_id) }
 
-            it "sets id attribute" do
-              expect(subject.instance_variable_get(:@id)).to eq(record_id)
-            end
-          end
+        it 'should not raise error' do
+          expect { subject }.to_not raise_error
+        end
 
-          context "with params" do
-            subject { described_class.new(record_id, params) }
+        it 'sets id attribute' do
+          expect(subject.instance_variable_get(:@id)).to eq(record_id)
+        end
+      end
 
-            it "should not raise error" do
-              expect { subject }.to_not raise_error
-            end
+      context 'with params' do
+        subject { described_class.new(record_id, params) }
 
-            it "sets params attribute" do
-              expect(subject.instance_variable_get(:@params)).to eq(params)
-            end
-          end
+        it 'should not raise error' do
+          expect { subject }.to_not raise_error
         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))
+        it 'sets params attribute' do
+          expect(subject.instance_variable_get(:@params)).to eq(params)
         end
       end
+    end
+  end
 
-      describe "#id=" do
-        subject { described_class.new(record_id) }
+  describe '#id' do
+    subject { described_class.new(record_id) }
+    it 'gets id attribute' do
+      expect(subject.id).to eq(subject.instance_variable_get(:@id))
+    end
+  end
 
-        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
+  describe '#id=' do
+    subject { described_class.new(record_id) }
 
-        context "invalid ID" do
-          it "raises error" do
-            expect { subject.id = "invalid" }.to raise_error('Invalid Europeana record ID: "invalid"')
-          end
-        end
+    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
 
-      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))
-        end
+    context 'invalid ID' do
+      it 'raises error' do
+        expect { subject.id = 'invalid' }.to raise_error('Invalid Europeana record ID: "invalid"')
       end
+    end
+  end
 
-      describe "#params=" do
-        subject { described_class.new(record_id, {}) }
+  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))
+    end
+  end
 
-        context "valid params" do
-          it "sets params attribute" do
-            subject.params = params
-            expect(subject.instance_variable_get(:@params)).to eq(params)
-          end
-        end
+  describe '#params=' do
+    subject { described_class.new(record_id, {}) }
 
-        it "validates param names" do
-          expect { subject.params = { :invalid => "parameter" } }.to raise_error(/Unknown key: :?invalid/)
-        end
+    context 'valid params' do
+      it 'sets params attribute' do
+        subject.params = params
+        expect(subject.instance_variable_get(:@params)).to eq(params)
       end
+    end
 
-      describe "#params_with_authentication" do
-        subject { described_class.new(record_id, params) }
+    it 'validates param names' do
+      expect { subject.params = { invalid: 'parameter' } }.to raise_error(/Unknown key: :?invalid/)
+    end
+  end
 
-        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
+  describe '#params_with_authentication' do
+    subject { described_class.new(record_id, params) }
 
-        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)
-          end
-        end
+    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
 
-      describe "#request_uri" do
-        subject { described_class.new(record_id, params) }
+    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)
+      end
+    end
+  end
 
-        it "returns a URI" do
-          expect(subject.request_uri).to be_a(URI)
-        end
+  describe '#request_uri' do
+    subject { described_class.new(record_id, params) }
 
-        it "includes the record ID" do
-          expect(subject.request_uri.to_s).to include(record_id)
-        end
+    it 'returns a URI' do
+      expect(subject.request_uri).to be_a(URI)
+    end
 
-        it "includes the query params" do
-          expect(subject.request_uri.to_s).to include(params.to_query)
-        end
-      end
+    it 'includes the record ID' do
+      expect(subject.request_uri.to_s).to include(record_id)
+    end
 
-      describe "#get" do
-        subject { described_class.new(record_id, params).get }
-        it_behaves_like "record request"
-      end
+    it 'includes the query params' do
+      expect(subject.request_uri.to_s).to include(params.to_query)
     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) }
+  end
 end

data/spec/spec_helper.rb

@@ -2,7 +2,7 @@ require 'coveralls'
 require 'europeana/api'
 require 'webmock/rspec'
 
-Dir["./spec/support/**/*.rb"].each { |f| require f }
+Dir['./spec/support/**/*.rb'].each { |f| require f }
 
 Coveralls.wear! unless Coveralls.will_run?.nil?
 

data/spec/support/shared_examples/record_request.rb

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

data/spec/support/webmock.rb

@@ -0,0 +1,14 @@
+RSpec.configure do |config|
+  config.before do
+    Europeana::API.api_key = 'xyz'
+
+    stub_request(:get, %r{www.europeana.eu/api/v2/record/[^/]+/[^/]+/self\.json}).
+      to_return(body: lambda { |_| '{"success":true, "self":{"id":"' + record_id + '", "childrenCount":0, "hasChildren":false}}' })
+
+    stub_request(:get, %r{www.europeana.eu/api/v2/record/[^/]+/[^/]+/parent\.json}).
+      to_return(body: lambda { |_| '{"success":true, "self":{"id":"' + record_id + '", "childrenCount":5, "hasChildren":false}, "parent":{}}' })
+
+    stub_request(:get, %r{www.europeana.eu/api/v2/record/[^/]+/[^/]+/children\.json}).
+      to_return(body: lambda { |_| '{"success":true, "self":{"id":"' + record_id + '", "childrenCount":5, "hasChildren":false}, "children":[]}' })
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: europeana-api
 version: !ruby/object:Gem::Version
-  version: 0.3.6
+  version: 0.4.1
 platform: ruby
 authors:
 - Richard Doe
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-09-23 00:00:00.000000000 Z
+date: 2015-11-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -115,11 +115,21 @@ files:
 - lib/europeana/api.rb
 - lib/europeana/api/errors.rb
 - lib/europeana/api/record.rb
+- lib/europeana/api/record/hierarchy.rb
+- lib/europeana/api/record/hierarchy/ancestor_self_siblings.rb
+- lib/europeana/api/record/hierarchy/base.rb
+- lib/europeana/api/record/hierarchy/children.rb
+- lib/europeana/api/record/hierarchy/following_siblings.rb
+- lib/europeana/api/record/hierarchy/parent.rb
+- lib/europeana/api/record/hierarchy/preceding_siblings.rb
+- lib/europeana/api/record/hierarchy/self.rb
 - lib/europeana/api/request.rb
+- lib/europeana/api/requestable.rb
 - lib/europeana/api/search.rb
 - lib/europeana/api/search/fields.rb
 - lib/europeana/api/version.rb
 - spec/europeana/api/errors_spec.rb
+- spec/europeana/api/record/hierarchy_spec.rb
 - spec/europeana/api/record_spec.rb
 - spec/europeana/api/search_spec.rb
 - spec/europeana/api_spec.rb
@@ -127,6 +137,7 @@ files:
 - spec/support/shared_examples/api_request.rb
 - spec/support/shared_examples/record_request.rb
 - spec/support/shared_examples/search_request.rb
+- spec/support/webmock.rb
 homepage: https://github.com/europeana/europeana-api-client-ruby
 licenses:
 - EUPL V.1.1
@@ -139,7 +150,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 1.9.2
+      version: 2.0.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
@@ -153,6 +164,7 @@ specification_version: 4
 summary: Ruby client library for the Europeana API
 test_files:
 - spec/europeana/api/errors_spec.rb
+- spec/europeana/api/record/hierarchy_spec.rb
 - spec/europeana/api/record_spec.rb
 - spec/europeana/api/search_spec.rb
 - spec/europeana/api_spec.rb
@@ -160,3 +172,4 @@ test_files:
 - spec/support/shared_examples/api_request.rb
 - spec/support/shared_examples/record_request.rb
 - spec/support/shared_examples/search_request.rb
+- spec/support/webmock.rb