europeana-api 0.5.2 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 330985d53a6b1fb63021e3144d271c09b518deab
-  data.tar.gz: 7d8c128ff306ba05a4f7a2a4e041c08fbce564b3
+  metadata.gz: a0b2c092e5307dddee16a30424d9f095d1881006
+  data.tar.gz: 9e55b99b93b151cf461c3ddf297329c163a7a3df
 SHA512:
-  metadata.gz: 66111e036999c9cabcbd0ce2bbccccf507cccca8ca6d963c8ca68deeb66d7af01588be958c7fc984aad2a88c56538e95ca6e5301562adb236d229b1517c7a393
-  data.tar.gz: 2d243b1d9e517e5b95a11d28e7853092421005541de037dfa824bc4b215113694d11e1e83cbfb88f2eb19fa9cae6f325646db3433f489b8c5faee1c216f2d3ec
+  metadata.gz: 57332276a79ed9680b91d31ed8439c67adef397fea3377062eb48797118796722d40e5506dd5fc829e13ea5e375ad81b0460495d1c8c125f3b0d1659756b003f
+  data.tar.gz: bfa182f373f3df742b5db95b3bb14ed9014b0c8ea99545e69ae5c37e1f52a02a9ef14c1104bd76f42e74185ef69a2f96e51cb174dfc74030335828b821eb43ee

data/.gitignore

@@ -2,6 +2,7 @@
 *.rbc
 .bundle
 .config
+/.ruby-version
 .yardoc
 Gemfile.lock
 InstalledFiles
@@ -15,3 +16,5 @@ spec/reports
 test/tmp
 test/version_tmp
 tmp
+/.env
+/.env.*

data/.travis.yml

@@ -1,12 +1,14 @@
 language: ruby
 rvm:
-  - 2.0.0
-  - 2.1.7
   - 2.2.2
   - 2.2.3
   - 2.3.1
+  - 2.3.3
+  - 2.4.0
 notifications:
   email: false
 sudo: false
 cache:
   bundler: true
+before_install:
+- gem update --system

data/Gemfile

@@ -1,12 +1,5 @@
+# frozen_string_literal: true
 source 'https://rubygems.org'
 
 # Specify your gem's dependencies in europeana.gemspec
 gemspec
-
-group :test do
-  gem 'coveralls', require: false
-end
-
-group :test, :develop do
-  gem 'rubocop', '0.39.0', require: false # only update when Hound does
-end

data/README.md

@@ -1,15 +1,13 @@
-# Europeana
+# Europeana API
 
-[![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)
+[![Build Status](https://travis-ci.org/europeana/europeana-api-client-ruby.svg?branch=develop)](https://travis-ci.org/europeana/europeana-api-client-ruby) [![Coverage Status](https://coveralls.io/repos/europeana/europeana-api-client-ruby/badge.svg?branch=develop&service=github)](https://coveralls.io/github/europeana/europeana-api-client-ruby?branch=develop) [![security](https://hakiri.io/github/europeana/europeana-api-client-ruby/develop.svg)](https://hakiri.io/github/europeana/europeana-api-client-ruby/develop) [![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/).
 
-## License
-
-Licensed under the EUPL V.1.1.
+## Requirements
 
-For full details, see [LICENSE.md](LICENSE.md).
+* Ruby >= 2.2.2
 
 ## Installation
 
@@ -21,19 +19,21 @@ gem 'europeana-api'
 
 And then execute:
 
-    $ bundle
+```
+bundle
+```
 
 Or install it yourself as:
 
-    $ gem install europeana-api
+```
+gem install europeana-api
+```
 
 ## Usage
 
 ### Authentication
 
-Authentication is *required* for all requests to the Europeana API.
-
-Only Basic Authentication (by API key) is supported.
+Authentication by API key is *required* for all requests to the Europeana API.
 
 Sign up for an API key at: http://labs.europeana.eu/api/registration/
 
@@ -41,26 +41,108 @@ Configure your application with the API key:
 
 ```ruby
 require 'europeana/api'
-Europeana::API.api_key = 'xyz'
+Europeana::API.key = 'xyz'
+```
+
+### Response format
+
+Responses from the API methods described below will by default be hashes with
+indifferent access, i.e. values can be retrieved by string or symbol keys.
+
+To have API methods return objects instead:
+```ruby
+Europeana::API.configure do |config|
+  config.parse_json_to = OpenStruct
+end
 ```
 
-### Search
+### Records
+
+#### Search
 
 ```ruby
-search = Europeana::API.search(query: '"first world war"') # => { "success" => true, "items" => [ ... ], "totalResults" => 1234, ... }
-search['items'] # => [ item1, item2, ... ]
-search['totalResults'] # => 1234
+search = Europeana::API.record.search(query: '"first world war"')
+search[:items] # => [ item1, item2, ... ]
+search[:totalResults] # => 81530
 ```
 
-See http://labs.europeana.eu/api/search/ for details of the data returned in
-the search response.
+See http://labs.europeana.eu/api/search/ for details of the available request
+parameters, and of the data returned in the search response.
 
-### Record
+#### Fetch
 
 ```ruby
-record = Europeana::API.record('/abc/1234') # => { "success" => true, "object" => { ... }, ... }
-record['object'] # => { "title" => "...", "proxies" => [ ... ], "aggregations" => [ ... ], ... }
+record = Europeana::API.record.fetch(id: '/92070/BibliographicResource_1000126223918')
+record[:object][:title] # => ["Panorama des Schafberges in Ober-Österreich. Blatt 1"]
+record[:object][:proxies].first[:dcCreator][:def] # => ["Simony, Friedrich"]
 ```
 
 See http://labs.europeana.eu/api/record/ for details of the data returned in
 the record response.
+
+#### Hierarchies
+
+```ruby
+hierarchy = Europeana::API.record.parent(id: '/2048604/data_item_onb_abo__2BZ17084070X')
+hierarchy[:parent][:id] # => "/2048604/data_item_onb_abo_AC10352829"
+```
+
+Methods available for hierarchy retrieval:
+```ruby
+Europeana::API.record.self
+Europeana::API.record.parent
+Europeana::API.record.children
+Europeana::API.record.preceding_siblings
+Europeana::API.record.following_siblings
+Europeana::API.record.ancestor_self_siblings
+```
+
+See http://labs.europeana.eu/api/hierarchical-records for details of the various
+hierarchy methods and their responses.
+
+### Annotations
+
+See http://labs.europeana.eu/api/annotations-methods for details of the responses
+received from the Annotations API methods.
+
+#### Search
+
+```ruby
+search = Europeana::API.annotation.search(query: 'music')
+search[:items].first # => "http://data.europeana.eu/annotation/collections/8"
+```
+
+#### Fetch
+
+```ruby
+annotation = Europeana::API.annotation.fetch(provider: 'collections', id: 8)
+annotation[:body] # => "Sheet music"
+```
+
+#### Create
+
+```ruby
+body = { bodyValue: 'Trombones', motivation: 'tagging', target: 'http://data.europeana.eu/item/09102/_UEDIN_214' }
+annotation = Europeana::API.annotation.create(userToken: 'secret-token', body: body.to_json)
+annotation[:id] # => "http://www.europeana.eu/api/annotations/myname/1234"
+```
+
+#### Update
+
+```ruby
+body = { bodyValue: 'Trombones', motivation: 'tagging' }
+annotation = Europeana::API.annotation.update(provider: 'myname', id: '1234', userToken: 'secret-token', body: body.to_json)
+annotation[:body][:value] # => "Trombones"
+```
+
+#### Delete
+
+```ruby
+Europeana::API.annotation.delete(provider: 'myname', id: '1234', userToken: 'secret-token') # => ""
+```
+
+## License
+
+Licensed under the EUPL V.1.1.
+
+For full details, see [LICENSE.md](LICENSE.md).

data/Rakefile

@@ -1,4 +1,5 @@
+# frozen_string_literal: true
 require 'bundler/gem_tasks'
 require 'rspec/core/rake_task'
-task :default => :spec
+task default: :spec
 RSpec::Core::RakeTask.new

data/bin/console

@@ -0,0 +1,21 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'dotenv'
+Dotenv.load
+
+require 'bundler/setup'
+require 'europeana/api'
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require 'pry'
+# Pry.start
+
+Europeana::API.key = ENV['EUROPEANA_API_KEY']
+Europeana::API.url = ENV['EUROPEANA_API_URL'] if ENV['EUROPEANA_API_URL']
+
+require 'irb'
+IRB.start

data/europeana-api.gemspec

@@ -1,4 +1,5 @@
 # coding: utf-8
+# frozen_string_literal: true
 lib = File.expand_path('../lib', __FILE__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require 'europeana/api/version'
@@ -20,11 +21,21 @@ Gem::Specification.new do |spec|
 
   spec.required_ruby_version = '>= 2.0.0'
 
-  spec.add_dependency 'activesupport', '>= 3.0', '< 5'
+  spec.add_dependency 'activesupport', '>= 4.2', '< 6.0'
+  # Locked to < v0.12.2 due to incompatibility with v0.12.2
+  # TODO: resolve incompatibility and unlock
+  spec.add_dependency 'faraday', '~> 0.9', '< 0.12.2'
+  spec.add_dependency 'faraday_middleware'
   spec.add_dependency 'multi_json', '~> 1.0'
+  spec.add_dependency 'rack', '> 1.6.2'
+  spec.add_dependency 'typhoeus', '~> 1.1'
 
   spec.add_development_dependency 'bundler', '~> 1.3'
+  spec.add_development_dependency 'coveralls'
+  spec.add_development_dependency 'dotenv'
   spec.add_development_dependency 'rake'
   spec.add_development_dependency 'rspec', '~> 3.0'
+  spec.add_development_dependency 'rubocop', '0.39.0' # only update when Hound does
+  spec.add_development_dependency 'shoulda-matchers', '~> 3.1'
   spec.add_development_dependency 'webmock', '~> 1.18.0'
 end

data/lib/europeana/api.rb

@@ -1,112 +1,88 @@
-require 'active_support/cache'
-require 'active_support/core_ext/object'
+# frozen_string_literal: true
+require 'active_support/concern'
+require 'active_support/core_ext/class/attribute'
 require 'active_support/core_ext/hash/indifferent_access'
 require 'active_support/core_ext/hash/slice'
+require 'active_support/core_ext/module/delegation'
+require 'active_support/core_ext/object'
 require 'active_support/hash_with_indifferent_access'
 require 'active_support/inflector/methods'
+require 'active_support/json'
 require 'europeana/api/version'
+require 'europeana/api/logger'
 require 'logger'
 require 'uri'
 
 module Europeana
   ##
-  # Europeana REST API client
+  # Interface to Europeana's RESTful API(s)
   module API
+    autoload :Annotation, 'europeana/api/annotation'
+    autoload :Client, 'europeana/api/client'
+    autoload :Entity, 'europeana/api/entity'
     autoload :Errors, 'europeana/api/errors'
+    autoload :FaradayMiddleware, 'europeana/api/faraday_middleware'
+    autoload :Queue, 'europeana/api/queue'
     autoload :Record, 'europeana/api/record'
     autoload :Request, 'europeana/api/request'
-    autoload :Requestable, 'europeana/api/requestable'
-    autoload :Search, 'europeana/api/search'
+    autoload :Resource, 'europeana/api/resource'
+    autoload :Response, 'europeana/api/response'
+
+    @url = 'https://www.europeana.eu/api'
 
     class << self
       ##
       # The Europeana API key, required for authentication
       #
       # @return [String]
-      attr_accessor :api_key
+      attr_accessor :key
 
       ##
       # The API's base URL
       #
       # @return [String]
       attr_accessor :url
-      
-      ##
-      # 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
 
       # @return [Logger]
       attr_writer :logger
 
-      attr_accessor :cache_store
+      def configuration
+        @configuration ||= Configuration.new
+      end
 
-      attr_accessor :cache_expires_in
+      def logger
+        @logger ||= defined?(Rails) && Rails.logger ? Rails.logger : Logger.new(STDOUT)
+      end
 
-      ##
-      # Sets configuration values to their defaults
-      def defaults!
-        self.url = 'https://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
+      def configure
+        yield(configuration)
       end
 
-      ##
-      # Sends a Search request to the Europeana API
-      #
-      # Equivalent to:
-      #   search = Europeana::API::Search.new(params)
-      #   search.execute
-      #
-      # @param [Hash] params Query parameters
-      # @return [Hash] search response
-      # @see Europeana::API::Search#execute
-      def search(params = {})
-        Search.new(params).execute
+      def in_parallel(&block)
+        client = Client.new
+        yield client.queue
+        client.queue.run
       end
 
-      ##
-      # Sends a Record request to the Europeana API
-      #
-      # Equivalent to:
-      #   record = Europeana::API::Record.new(record_id, params)
-      #   record.get(options)
-      #
-      # @param [String] Record ID
-      # @param [Hash] params Query parameters
-      # @param [Hash] options (see Europeana::API::Record#get)
-      # @return [Hash] search response
-      # @see Europeana::API::Record#get
-      def record(record_id, params = {}, options = {})
-        Record.new(record_id, params).get(options)
+      def annotation
+        Annotation
       end
 
-      def logger
-        return @logger unless @logger.nil?
+      def record
+        Record
+      end
 
-        @logger = case
-        when defined?(Rails) && Rails.logger
-          Rails.logger
-        else
-          Logger.new(STDOUT)
-        end
+      def entity
+        Entity
       end
     end
 
-    self.defaults!
+    class Configuration
+      attr_accessor :parse_json_to
+
+      def initialize
+        @parse_json_to = Hash
+      end
+    end
   end
 end

data/lib/europeana/api/annotation.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+module Europeana
+  module API
+    ##
+    # An annotation of a Europeana object
+    #
+    # @see http://labs.europeana.eu/api/annotations
+    class Annotation
+      include Resource
+
+      has_api_endpoint :search, method: :get, path: '/annotations/search'
+      has_api_endpoint :fetch, method: :get, path: '/annotations/%{provider}/%{id}'
+      has_api_endpoint :create, method: :post, path: '/annotations/',
+                                headers: { 'Content-Type' => 'application/ld+json' }
+      has_api_endpoint :update, method: :put, path: '/annotations/%{provider}/%{id}',
+                                headers: { 'Content-Type' => 'application/ld+json' }
+      has_api_endpoint :delete, method: :delete, path: '/annotations/%{provider}/%{id}'
+    end
+  end
+end