Merge pull request scotdalton#4 from ntechmedia/feature/rest_api_support

Feature/rest api support

.gitignore

@@ -2,5 +2,8 @@ Gemfile.lock
 pkg/
 *.bak
 coverage/
+.ruby-gemset
 .ruby-version
 *.gem
+.idea
+sandpit

.travis.yml

@@ -1,7 +1,7 @@
 language: ruby
 rvm:
-  - 2.1.10
-  - 2.2.6
-  - 2.3.3
-  - jruby-9.1.8.0
+  - 2.3.8
+  - 2.4.6
+  - 2.5.5
+  - 2.6.3
 install: "bundle install --retry=3"

README.md

@@ -12,101 +12,264 @@ and exposes the set of holdings, fulltext links, table of contents links, and re
 
 ### Example of Exlibris::Primo::Search in action
 Search can search by a query
+```ruby
+search = Exlibris::Primo::Search.new(
+  :base_url => "http://primo.institution.edu",
+  :institution => "INSTITUTION", 
+  :page_size => "20"
+)
+search.add_query_term "0143039008", "isbn", "exact"
 
-    search = Exlibris::Primo::Search.new(:base_url => "http://primo.institution.edu",
-      :institution => "INSTITUTION", :page_size => "20")
-    search.add_query_term "0143039008", "isbn", "exact"
-    count = search.size #=> 20+ (assuming there are 20+ records with this isbn)
-    facets = search.facets #=> Array of Primo facets
-    records = search.records #=> Array of Primo records
-    records.size #=> 20 (assuming there are 20+ records with this isbn)
-    records.each do |record_id, record|
-      holdings = record.holdings #=> Array of Primo holdings
-      fulltexts = record.fulltexts #=> Array of Primo full texts
-      table_of_contents = record.table_of_contents #=> Array of Primo tables of contents
-      related_links = record.related_links #=> Array of Primo related links
-    end
+count = search.size #=> 20+ (assuming there are 20+ records with this isbn)
+facets = search.facets #=> Array of Primo facets
+records = search.records #=> Array of Primo records
+records.size #=> 20 (assuming there are 20+ records with this isbn)
+records.each do |record_id, record|
+  holdings = record.holdings #=> Array of Primo holdings
+  fulltexts = record.fulltexts #=> Array of Primo full texts
+  table_of_contents = record.table_of_contents #=> Array of Primo tables of contents
+  related_links = record.related_links #=> Array of Primo related links
+end
+```
 
 Or by a given record id
 
-    search = Exlibris::Primo::Search.new(:base_url => "http://primo.institution.edu",
-      :institution => "INSTITUTION")
-    search.record_id! "aleph0123456789"
-    count = search.size #=> 1
-    records = search.records #=> Array of Primo records
-    records.size #=> 1
-    record = records.first #=> Primo record
-    holdings = record.holdings #=> Array of Primo holdings
-    fulltexts = record.fulltexts #=> Array of Primo full texts
-    table_of_contents = record.table_of_contents #=> Array of Primo tables of contents
-    related_links = record.related_links #=> Array of Primo related links
+```ruby
+search = Exlibris::Primo::Search.new(
+  :base_url => "http://primo.institution.edu",
+  :institution => "INSTITUTION"
+)
+search.record_id! "aleph0123456789"
+
+count = search.size #=> 1
+records = search.records #=> Array of Primo records
+records.size #=> 1
+record = records.first #=> Primo record
+holdings = record.holdings #=> Array of Primo holdings
+fulltexts = record.fulltexts #=> Array of Primo full texts
+table_of_contents = record.table_of_contents #=> Array of Primo tables of contents
+related_links = record.related_links #=> Array of Primo related links
+```
 
 Search has some methods for setting search params
 
-    search = Exlibris::Primo::Search.new(:base_url => "http://primo.institution.edu",
-      :institution => "INSTITUTION")
-    search.isbn_is "0143039008" #=> Equivalent to search.add_query_term "0143039008", "isbn", "exact"
-    search.title_begins_with "Travels" #=> Equivalent to search.add_query_term "Travels", "title", "begins_with"
-    search.creator_contains "Greene" #=> Equivalent to search.add_query_term "Greene", "creator", "contains"
+```ruby
+search = Exlibris::Primo::Search.new(
+  :base_url => "http://primo.institution.edu",
+  :institution => "INSTITUTION"
+)
+search.isbn_is "0143039008" #=> Equivalent to search.add_query_term "0143039008", "isbn", "exact"
+search.title_begins_with "Travels" #=> Equivalent to search.add_query_term "Travels", "title", "begins_with"
+search.creator_contains "Greene" #=> Equivalent to search.add_query_term "Greene", "creator", "contains"
+```
 
 Search can take a record id the initial hash
 
-    search = Exlibris::Primo::Search.new(:base_url => "http://primo.institution.edu",
-      :institution => "INSTITUTION", :record_id => "aleph0123456789")
-
+```ruby
+search = Exlibris::Primo::Search.new(
+  :base_url => "http://primo.institution.edu",
+  :institution => "INSTITUTION", 
+  :record_id => "aleph0123456789"
+)
+```
 Search can also be chained using the ! version of the attribute writer
 
-    search = Exlibris::Primo::Search.new.base_url!("http://primo.institution.edu").
-      institution!("INSTITUTION").record_id!("aleph0123456789")
-
+```ruby
+search = Exlibris::Primo::Search.new
+  .base_url!("http://primo.institution.edu")
+  .institution!("INSTITUTION")
+  .record_id!("aleph0123456789")
+```
 Or
 
-    search = Exlibris::Primo::Search.new.base_url!("http://primo.institution.edu").
-      institution!("INSTITUTION").title_begins_with("Travels").
-        creator_contains("Greene").genre_is("Book")
+```ruby
+search = Exlibris::Primo::Search.new
+  .base_url!("http://primo.institution.edu")
+  .institution!("INSTITUTION")
+  .title_begins_with("Travels")
+  .creator_contains("Greene")
+  .genre_is("Book")
+```
+Search can be expanded when using Ex Libris Primo Central by adding a request parameter true
+
+```ruby
+search = Exlibris::Primo::Search.new(
+  :base_url => "http://primo.institution.edu",
+  :institution => "INSTITUTION", 
+  :page_size => "20"
+)
+search.add_query_term "0143039008", "isbn", "exact"
+search.add_request_param('pc_availability_ind','true') # adding this line will expand the results
+
+count = search.size #=> 20+ (assuming there are 20+ records with this isbn)
+facets = search.facets #=> Array of Primo facets
+
+records = search.records #=> Array of Primo records
+records.size #=> 20 (assuming there are 20+ records with this isbn)
+records.each do |record_id, record|
+  holdings = record.holdings #=> Array of Primo holdings
+  fulltexts = record.fulltexts #=> Array of Primo full texts
+  table_of_contents = record.table_of_contents #=> Array of Primo tables of contents
+  related_links = record.related_links #=> Array of Primo related links
+end
+```
+
+### Facets for the REST API
+The REST API implementation allows you to include or exclude facets as part of your query parameters.  To include or 
+exclude facets in your search you can do the following:
+
+```ruby
+search = Exlibris::Primo::Search.new(
+  :api => :rest,
+  :api_key => 'l7xxcb1e0f7b1d9340123edf456ec789f95d',
+  :vid => 'ALL',
+  :tab => 'quicksearch',
+  :base_url => "http://primo.institution.edu",
+  :institution => "INSTITUTION"
+)
+
+
+search.add_facet 'books', 'facet_rtype' # Implicitly include resources with the type of book
+search.add_facet 'Jack Johnson', 'facet_creator', true # Explicitly include Jack Johnson as the resource creator
+search.add_facet 'Archives', 'facet_library', false # Exclude library archives
+```
+
+Currently the following facet categories are supported:
+
+- __facet_rtype__: Resource Type
+- __facet_topic__: Subject
+- __facet_creator__: Author
+- __facet_tlevel__: Availability
+- __facet_domain__: Collection
+- __facet_library__: Library name
+- __facet_lang__: Language
+- __facet_lcc__: LCC classification
+
+You can programmatically get them from the following class method:
+
+```ruby
+Exlibris::Primo::WebService::Request::Facet.allowed_categories
+```
+
 
 ## Exlibris::Primo::Config
 Exlibris::Primo::Config allows you to specify global configuration parameter for Exlibris::Primo
 
-    Exlibris::Primo.configure do |config|
-      config.base_url = "http://primo.institution.edu"
-      config.institution = "INSTITUTION"
-      config.libraries = { "LIB_CODE1" => "Library Decoded 1", "LIB_CODE2" => "Library Decoded 2",
-        "LIB_CODE3" => "Library Decoded 3" }
-    end
-
+```ruby
+Exlibris::Primo.configure do |config|
+  config.base_url = "http://primo.institution.edu"
+  config.institution = "INSTITUTION"
+  config.libraries = { 
+    "LIB_CODE1" => "Library Decoded 1", 
+    "LIB_CODE2" => "Library Decoded 2",
+    "LIB_CODE3" => "Library Decoded 3" 
+  }
+end
+```
 Exlibris::Primo::Config can also read in from a YAML file that specifies the various config elements
 
-    Exlibris::Primo.configure do |config|
-      config.load_yaml "./config/primo.yml"
-    end
+```ruby
+Exlibris::Primo.configure do |config|
+  config.load_yaml "./config/primo.yml"
+end
+```     
+
+## API Choice    
+Currently Exlibris provides a fully featured [SOAP API](https://developers.exlibrisgroup.com/primo/apis/webservices/soap) 
+and a REST API (see [Primo REST APIs](https://developers.exlibrisgroup.com/primo/apis/webservices/rest) which, supports
+a [Brief Search](https://developers.exlibrisgroup.com/primo/apis/search/GET/AnSF56/p3aKzRujr9pj8qtyT3YiaSYVA/f5643222-bb88-4f3d-b2d6-5029e527c515)) 
+with limited features.  To choose the API you want to use you can do this at the time of instance creation for the 
+various classes (e.g.  `Exlibris::Primo::EShelf`, `Exlibris::Primo::Search`, etc) or set it globally in the `Exlibris::Primo.config`.  
+
+
+### Choosing the SOAP API
+To use the SOAP API you can specify it in your requests as follows:
+```ruby
+eshelf = Exlibris::Primo::EShelf.new(
+  :api => :soap,
+  :user_id => "USER_ID",
+  :base_url => "http://primo.institution.edu", 
+  :insitution => "INSTITUTION"
+)
+```
+__NB:__ If you don't provided the `api` param it will default to `:soap`  
+
+### Choosing the REST API
+To use the REST API you will need to not only provide the `api` but also the `api_key`.  Specifically for search you 
+will also need to include the `vid` (view id) and `tab` (e.g. default_search, quicksearch, etc) based on the configuration 
+of the Exlibrish Primo instance.  Following is an example
+```ruby
+search = Exlibris::Primo::Search.new(
+  :api => :rest,
+  :api_key => 'l7xxcb1e0f7b1d9340123edf456ec789f95d',
+  :vid => 'ALL',
+  :tab => 'quicksearch',
+  :base_url => "http://primo.institution.edu",
+  :institution => "INSTITUTION"
+)
+```
+__NB:__ If you don't provided the `api` param it will default to `:soap`  
+
+### Choosing the API via configuration
+To choose the API globally using the configuration you can use one of the two approaches:
+
+```ruby
+Exlibris::Primo.configure do |config|
+  config.api :rest
+end
+
+# OR
+
+Exlibris::Primo.config.api = :rest
+```
+
+__N.B.__: As mentioned earlier the REST API only supports a subset of the features provided by the SOAP API so global 
+setting should be done with caution. 
+
 
 ## Exlibris::Primo::EShelf
 The Exlibris::Primo::EShelf class provides methods for reading a given user's Primo eshelf
 and eshelf structure as well as adding and removing records.
 
 ## Example of Exlibris::Primo::EShelf in action
-    eshelf = Exlibris::Primo::EShelf.new(:user_id => "USER_ID",
-      :base_url => "http://primo.institution.edu", :insitution => "INSTITUTION")
-    records = eshelf.records
-    size = eshelf.size
-    basket_id = eshelf.basket_id
-    eshelf.add_records(["PrimoRecordId","PrimoRecordId2"], basket_id)
+```ruby
+eshelf = Exlibris::Primo::EShelf.new(
+  :user_id => "USER_ID",
+  :base_url => "http://primo.institution.edu", 
+  :insitution => "INSTITUTION"
+)
+records = eshelf.records
+size = eshelf.size
+basket_id = eshelf.basket_id
+eshelf.add_records(["PrimoRecordId","PrimoRecordId2"], basket_id)
+```
 
 ## Exlibris::Primo::Reviews
 The Exlibris::Primo::Reviews class provides methods for reading a given user's Primo reviews
 features.
 
 ## Example of Exlibris::Primo::Reviews in action
-    reviews = Exlibris::Primo::Reviews.new(:record_id => "aleph0123456789", :user_id => "USER_ID",
-      :base_url => "http://primo.institution.edu", :insitution => "INSTITUTION")
-    user_record_reviews = reviews.reviews #=> Array of Primo reviews
+```ruby
+reviews = Exlibris::Primo::Reviews.new(
+  :record_id => "aleph0123456789", 
+  :user_id => "USER_ID",
+  :base_url => "http://primo.institution.edu", 
+  :insitution => "INSTITUTION"
+)
+user_record_reviews = reviews.reviews #=> Array of Primo reviews
+```
 
 ## Exlibris::Primo::Tags
 The Exlibris::Primo::Tags class provides methods for reading a given user's Primo tags
 features.
 
 ## Example of Exlibris::Primo::Tags in action
-    tags = Exlibris::Primo::Tags.new(:record_id => "aleph0123456789", :user_id => "USER_ID",
-      :base_url => "http://primo.institution.edu", :insitution => "INSTITUTION")
-    user_record_tags = tags.tags #=> Array of Primo tags
+```ruby
+tags = Exlibris::Primo::Tags.new(
+  :record_id => "aleph0123456789", 
+  :user_id => "USER_ID",
+  :base_url => "http://primo.institution.edu", 
+  :insitution => "INSTITUTION"
+)
+user_record_tags = tags.tags #=> Array of Primo tags
+```

exlibris-primo.gemspec

@@ -19,14 +19,15 @@ Gem::Specification.new do |s|
 
   s.add_dependency 'require_all', '~> 1.3'
   # Leverage ActiveSupport core extensions.
-  s.add_dependency 'activesupport', '>= 3.2', '< 5'
+  s.add_dependency 'activesupport', '>= 3.2', '< 3.3'
   s.add_dependency 'nokogiri', '< 2'
   s.add_dependency 'json', '>= 1.8.0', '< 3'
   s.add_dependency 'savon', '~> 2.11'
+  s.add_dependency 'faraday', '1.0.1'
   s.add_dependency 'iso-639', '~> 0.2.0'
   s.add_development_dependency 'rake', '~> 10.1'
-  s.add_development_dependency 'vcr', '~> 2.9'
-  s.add_development_dependency 'webmock', '~> 1.20'
+  s.add_development_dependency 'vcr', '~> 6.0.0'
+  s.add_development_dependency 'webmock', '~> 3.12'
   s.add_development_dependency 'pry', '~> 0'
   s.add_development_dependency 'minitest', '~> 4.7'
   s.add_development_dependency 'rack', '~> 1.6'

lib/exlibris/primo/api.rb

@@ -0,0 +1,9 @@
+module Exlibris
+  module Primo
+    module Api
+      def current_api
+        (methods.include?(:api) ? (api || Exlibris::Primo.config.api) : (Exlibris::Primo.config.api)) || :soap
+      end
+    end
+  end
+end