alma_api 1.0.2 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: be075de2651cd726b827c48274a0a71338e21064cb33433597c9e09cafabdf41
-  data.tar.gz: 972119e4a07785159951b1a29f98636608d46c8ce2b8179465191ff3af3804d4
+  metadata.gz: '0285277d54273b7ad7bc88e92941b3b5dc8d687f185da09e178b4634374f9888'
+  data.tar.gz: 74705ba4e5216b96c4c2855a6122d888d26fcf13d5c59cc2d6816851971b573a
 SHA512:
-  metadata.gz: cc56000113b9aebc0987713e9ebc74a2e52144989fe66dedf6f9b2f8aa128bef2af402e07211a07abcb6bd20f35d480f2fe7beaaed0a4b1626661772a9826834
-  data.tar.gz: 42d7d770833351af4aea0f0bd26bf4920f46fc66ccbf081c079c2f1cb0707a660d27163cf2d3cbd0792e4570e7b7ab5e09163da78acf7f888a81f9608be821fe
+  metadata.gz: bdf8362e4e389cecb7c5d51627115b54d764696903b1745415a651bc375788c4b12b8c061dd476222e60b7f714a100d0a419ba755f017bc8bd2761bcac4ea9c2
+  data.tar.gz: afe0e7c68cfb16c0564dad09b7a67dd2896b023abf9a710e7dbd58d1e2815a7999a9b2e6f23846d1644f516537e2621161dc2abc32669919cdd5ce683cdb8955

data/README.md

@@ -13,7 +13,7 @@ The main purpose of this library is to abstract authentication, error handling,
 
 It uses [`faraday`](https://github.com/lostisland/faraday) as the underlying http client, [`nokogiri`](https://github.com/sparklemotion/nokogiri) for XML parsing, and [`oj`](https://github.com/ohler55/oj) and [`hashie`](https://github.com/hashie/hashie) for JSON processing.
 
-__Note: This is NOT an official Alma API client. It is developed at the University Library of Paderborn as an open source project.__
+__Note: This is _NOT_ an official Alma API client. It is developed at the [University Library of Paderborn](https://ub.uni-paderborn.de) as an open source project and used in production as part of the library's [discovery portal](https://katalog.ub.uni-paderborn.de).__
 
 ## Installation
 
@@ -28,38 +28,64 @@ and run the `bundle install` command in your terminal.
 
 > You need an API key for your Alma Instance in order to use this client. Please consult the [Ex Libris developer documentation on how to use the Alma REST APIs](https://developers.exlibrisgroup.com/alma/apis/#using) for more information how to get and setup your API keys.
 
+__Note: There a some breaking changes when upgrading from 1.x to 2.x. [Please read the section on upgrading below](#upgrading).__
+
+### Quick example
+
+Here is a minimal example to get started. Read the sections below for more information on how to use this library.
+
+```ruby
+# Create a client
+client = AlmaApi::Client.configure do |config|
+  config.api_key = "YOUR API KEY"
+end
+
+# Use the client to get some users
+users = client.get("users", params: {limit: 2})
+```
+
 ### Creating a configuration
 
-To use this library you need an `AlmaApi::Client` instance. The client requires an `AlmaApi::Configuration`.
+To use this library you need an `AlmaApi::Client` instance. To create a client you first need an `AlmaApi::Configuration`.
 
 ```ruby
-configuration = AlmaApi::Configuration.new(
-  api_key: "...",        # 1. required
-  base_url: "...",       # 2. optional
-  default_format: "...", # 3. optional
-  language: "..."        # 4. optional
-)
+# Normal method
+configuration = AlmaApi::Configuration.new(api_key: "YOUR API KEY")
+# ... or
+configuration = AlmaApi::Configuration.new
+configuration.api_key = "YOUR API KEY"
+
+# Block-style
+configuration = AlmaApi::Configuration.new do |config|
+  config.api_key = "YOUR API KEY"
+end
 ```
+The API key is the only required option to get a functional configuration. There are sensible default values for all other options.
+
+The following options are available:
 
 1. `api_key`
-    Add your Alma API key here.
+    Set your Alma API key. This is the only option that can be passed to the constructor as a shortcut. All other options must be set using setters.
 2. `base_url`
-    Add the base URL to be used for each request. Ex Libris provides different API gateways for different geographical locations. See [the documentation here](https://developers.exlibrisgroup.com/alma/apis/#calling) for more information. This parameter is optional and defaults to the Alma API Gateway for Europe: `https://api-eu.hosted.exlibrisgroup.com/almaws/v1`.
+    Set the base URL to be used for each request. Ex Libris provides different API gateways for different geographical locations. See [the documentation here](https://developers.exlibrisgroup.com/alma/apis/#calling) for more information. This parameter is optional and defaults to the Alma API Gateway for Europe: `https://api-eu.hosted.exlibrisgroup.com/almaws/v1`.
 
-    You can use a `Symbol` as a shortcut to set the `base_url` for one of the preconfigured gateways `:na` (North America), `:eu` (Europe), `:ap` (Asia-Pacific), `:ca` (Canada), `:cn` (China).
+    This expects a `String` with a valid URL. However, you can use a `Symbol` as a shortcut to set the `base_url` for one of the preconfigured gateways `:na` (North America), `:eu` (Europe), `:ap` (Asia-Pacific), `:ca` (Canada), `:cn` (China).
 
     For example, to set the `base_url` for the canadian gateway, use
 
     ```ruby
-      configuration = AlmaApi::Configuration.new(
-        base_url: :ca,
-        ...
+      configuration = AlmaApi::Configuration.new do |config|
+        config.api_key  = "YOUR API KEY"
+        config.base_url = :ca
       )
     ```
 3. `default_format`
-    The default format to use for each request. The client supports `json` and `xml`. The default is `json`.
+    The default format to use for each request. The client supports `"json"` and `"xml"`. The default is `"json"`.
 4. `language`
-    The language used by Alma for error messages and textual information. The default is English (`en`). To change this, set this parameter to any 2-letter language code that is supported and enabled in Alma (see the mapping table "Institution Languages" in Alma).
+    The language used by Alma for error messages and textual information. The default is English (`"en"`). To change this, set this parameter to any 2-letter language code that is supported and enabled in Alma (see the mapping table "Institution Languages" in Alma).
+5. `timeout`
+    The max number of seconds (Integer, Float) to wait for a request to complete. The default is `nil` which uses
+    the default of the underlying Faraday adapter (`Net::HTTP`).
 
 ### Creating a client
 
@@ -68,28 +94,31 @@ With the configuration ready, you can create the client.
 ```ruby
 client = AlmaApi::Client.new(configuration)
 ```
-
-As a shortcut, you can call `AlmaApi.configure` to get the client instance. Note that each call to `AlmaApi.configure` returns a new `AlmaApi::Client` instance.
+As a shortcut, you can call `AlmaApi.configure` with a block to get the client instance. Note that each call to `AlmaApi.configure` returns a new `AlmaApi::Client` instance.
 
 ```ruby
-client = AlmaApi.configure do |config|
+client = AlmaApi::Client.configure do |config|
   config.api_key = "..."
-  config.base_url = "..."
-  config.default_format = "..."
-  config.language = "..."
+  ...
 end
 ```
 ### Using the client
 
+#### Calling Alma
+
 The client provides the following methods: `#get`, `#post`, `#put` and `#delete` to call the Alma APIs with the corresponding HTTP methods `GET`, `POST`, `PUT` and `DELETE`.
 
 Each method expects a URL path to the resource relative to the configured `base_url` as it's first parameter. Parameters that the Alma API expects as part of the URL path must be included here.
 
-To set query string parameters, set the `params:` option and provide a Ruby `hash`. To override the `default_format` for an individual request, you can set the `format:` option to `json` or `xml`, depending on your needs. Setting the format to `xml` is preferable for Alma APIs that work with MARCXML data.
+To set query string parameters, set the `params:` option and provide a Ruby `hash`. To override the `default_format` for an individual request, you can set the `format:` option to `"json"` or `"xml"`, depending on your needs. Setting the format to `"xml"` is preferable for Alma APIs that work with MARCXML data.
+
+To set the body of a `#post` or `#put` request, you can set the `body:` option. If the request format is `"json"`, the `body:` option should contain a valid json string. Otherwise, if the request format is `"xml"`, the option should be a valid XML string.
+
+In the case of a JSON request, the result of the call is a Ruby `hash`. For a XML request, the result is a `Nokogiri::XML::Document` instance, as this library uses [`nokogiri`](https://github.com/sparklemotion/nokogiri) under the hood for XML processing.
 
-To set the body of a `#post` or `#put` request, you can set the `body:` option. If the request format is `json`, the `body:` option should contain a valid json string. Otherwise, if the request format is `xml`, the option should be a valid XML string.
+#### Get remaining API calls
 
-In the case of a `json` request, the result of the call is a Ruby `hash`. For `xml`, the result is a `Nokogiri::XML::Document` instance, as this library uses [`nokogiri`](https://github.com/sparklemotion/nokogiri) under the hood for XML processing.
+Alma reports the number of remaining API calls as part of the response. You can call `#remaining_api_calls` on the client to get this number. In case of an error this simply returns `-1`.
 
 ## Examples
 
@@ -156,11 +185,22 @@ client.delete("users/#{user_id}") # user_id is a URL parameter
 
 ## Error handling
 
-There are three types of errors that can occur when calling the Alma APIs with this library. Each error exposes the `#message` and `#code` methods for further inspection. The message is returned in the language set in the configuration (default is English).
+There are four types of errors that can occur when calling the Alma APIs with this library.
 
-For gateway errors, the code is a string token (e.g. REQUEST_TOO_LARGE). For logical errors, the code is usually a number (e.g. 401850). See the "Possible Error Codes" section for each resource in the [documentation](https://developers.exlibrisgroup.com/alma/apis/) for details.
+### 1. `AlmaApi::Error`
 
-### 1. `AlmaApi::GatewayError`
+This is the base error class for this library. All errors raised within this library during a request will result in an `AlmaApi::Error` or in one of the more specific sub classes listed below.
+
+This error is also raised if something goes wrong when opening the connection, on SSL errors, network timeouts, etc.
+
+The original error is wrapped and is available via the `#cause` method.
+
+Each error exposes `#message` and `#code` methods for further inspection.
+Messages that are generated by Alma are returned in the language set in the configuration (default is English).
+
+The code is generated by Alma. For gateway errors, the code is a string token (e.g. REQUEST_TOO_LARGE). For logical errors, the code is usually a number (e.g. 401850). See the "Possible Error Codes" section for each resource in the [documentation](https://developers.exlibrisgroup.com/alma/apis/) for details.
+
+### 2. `AlmaApi::GatewayError`
 
 If the Alma API responds with a `4xx` OR `5xx` HTTP status AND one of the following error codes, an `AlmaApi::GatewayError` is thrown.
 
@@ -178,7 +218,7 @@ Any `4xx` HTTP status that does not result in an `AlmaApi::GatewayError` will be
 
 This is the most common error you will encounter and can be used to manage the control flow in your application.
 
-For example, if you're loading a user's details, you don't want your application to blow up if a user with the specified user ID doesn't exist. Instead, you can handle the error like this:
+For example, if you're loading a user's details, you usually don't want your application to blow up if a user with the specified user ID doesn't exist. Instead, you can handle the error like this:
 
 ```ruby
 def load_user(user_id)
@@ -200,3 +240,26 @@ else
 end
 
 ```
+
+## Tweaking a request
+
+As stated before this library uses [`faraday`](https://github.com/lostisland/faraday) as the underlying http client. It manages the Faraday connection, sets up the necessary headers and params and performs the requests against Alma.
+
+Therefore there should be no need to tweak a request before sending it to Alma. This should be considered as a bug and we are happy to receive feature requests.
+
+However, there is a way to tweak a request. For `#get`, `#post`, `#put` and `#delete` you can open a block that gives you access to the [`Faraday::Request`](https://www.rubydoc.info/github/lostisland/faraday/Faraday/Request) instance.
+
+```ruby
+client.get("some/path") do |req|
+  req.headers["foo"] = "bar"
+end
+```
+
+## Upgrading
+
+### From 1.x to 2.x
+
+* `AlmaApi.configure` is deprecated. Use `AlmaApi::Client.configure` instead.
+* All errors that get raised during a request result in an `AlmaApi::Error`. Use `#cause` to get the causing error.
+* `AlmaApi::Client#remaining_api_calls` performs a request to read the value from Alma.
+* `AlmaApi::Configuration` can be used to set a request timeout.

data/lib/alma_api/client.rb

@@ -1,8 +1,14 @@
 module AlmaApi
   class Client
+    class << self
+      def configure
+        configuration = Configuration.new
+        yield(configuration) if block_given?
+        new(configuration)
+      end
+    end
 
-    attr_reader :configuration,
-                :remaining_api_calls
+    attr_reader :configuration
 
     def initialize(configuration)
       @configuration = configuration
@@ -11,7 +17,9 @@ module AlmaApi
 
     def get(url, params: {}, format: nil)
       perform_request do
-        connection(format: format, params: params).get(url)
+        connection(format: format, params: params).get(url) do |req|
+          yield(req) if block_given?
+        end
       end
     end
 
@@ -19,6 +27,7 @@ module AlmaApi
       perform_request do
         connection(format: format, params: params).post(url) do |req|
           req.body = body
+          yield(req) if block_given?
         end
       end
     end
@@ -27,19 +36,32 @@ module AlmaApi
       perform_request do
         connection(format: format, params: params).put(url) do |req|
           req.body = body
+          yield(req) if block_given?
         end
       end
     end
 
     def delete(url, params: {}, format: nil)
       perform_request do
-        connection(format: format, params: params).delete(url)
+        connection(format: format, params: params).delete(url) do |req|
+          yield(req) if block_given?
+        end
       end
     end
 
+    def remaining_api_calls
+      response = connection.get("users/operation/test")
+      rac = response.headers["x-exl-api-remaining"]
+      rac.present? ? rac.to_i : -1
+    rescue StandardError
+      -1
+    end
+
   private
 
     def connection(format: nil, params: {})
+      # The format parameter is used to specify the format of the request.
+      # Alma supports both JSON and XML, but the default is JSON.
       format = case AlmaApi.validate_format!(format)
                when "xml"  then "application/xml"
                when "json" then "application/json"
@@ -47,20 +69,40 @@ module AlmaApi
                  "application/json"
                end
 
+      # Setup default parameters. For now just the language.
+      # If the language is not specified, then the default language is English.
       default_params = {
         lang: configuration.language
       }.reject do |k, v|
         k == :lang && (v.blank? || v == "en")
       end
 
+      # Merge the default parameters with the parameters passed in.
+      params = default_params.reverse_merge(params)
+
+      # Setup the headers for the request.
+      headers = {
+        "Authorization" => "apikey #{configuration.api_key}",
+        "Accept"        => format,
+        "Content-Type"  => format
+      }
+
+      # If the params contains a password parameter, delete that from the params
+      # and add it to the headers. This is a special case for the Alma API when
+      # authenticating a user.
+      # @see https://developers.exlibrisgroup.com/alma/apis/docs/users/UE9TVCAvYWxtYXdzL3YxL3VzZXJzL3t1c2VyX2lkfQ==/
+      if (password = params.delete(:password) || params.delete("password")).present?
+        headers["Exl-User-Pw"] = password
+      end
+
+      # Finally create and return the Faraday connection object.
       Faraday.new(
         configuration.base_url,
-        params:  default_params.reverse_merge(params),
-        headers: {
-          "Authorization": "apikey #{configuration.api_key}",
-          "Accept":        format,
-          "Content-Type":  format
-        }
+        request: {
+          timeout: configuration.timeout
+        },
+        params:  params,
+        headers: headers
       ) do |faraday|
         faraday.response :raise_error # raise Faraday::Error on status code 4xx or 5xx
       end
@@ -68,31 +110,32 @@ module AlmaApi
 
     def perform_request
       response = yield
-      set_remaining_api_calls(response)
       parse_response_body(response.body)
     rescue Faraday::Error => e
       handle_faraday_error(e)
+    rescue StandardError
+      raise Error, GENERAL_ERROR_MESSAGE
     end
 
     def handle_faraday_error(error)
-      error_response = parse_error_response_body(error.response_body)
+      # The error response body is either XML, JSON or empty, so we need to parse it
+      error_message, error_code = parse_error_response_body(error.response_body)
 
-      case error_response[:error_code]
-      when *GATEWAY_ERROR_CODES
-        raise GatewayError.new(error_response[:error_message], error_response[:error_code])
-      else
+      if error_message.present? && error_code.present?
+        # Raise a gateway error if the error code is one of the gateway error codes
+        raise GatewayError.new(error_message, error_code) if GATEWAY_ERROR_CODES.include?(error_code)
+
+        # Check the response status code
         case error.response_status
         when 400..499
-          raise LogicalError.new(error_response[:error_message], error_response[:error_code])
-        else
-          raise ServerError.new(error_response[:error_message], error_response[:error_code])
+          raise LogicalError.new(error_message, error_code)
+        when 500..599
+          raise ServerError.new(error_message, error_code)
         end
       end
-    end
 
-    def set_remaining_api_calls(response)
-      rac = response.headers[:x_alma_api_remaining]
-      @remaining_api_calls = rac.to_i if rac.present?
+      # If we get here, then we don't know what the error is, so we raise a generic error.
+      raise Error, GENERAL_ERROR_MESSAGE
     end
 
     def parse_response_body(body)
@@ -108,12 +151,13 @@ module AlmaApi
     end
 
     def parse_error_response_body(body)
+      error_message = nil
+      error_code = nil
+
       if is_xml_response?(body)
         xml = Nokogiri::XML.parse(body)
-        error_message = xml.at("errorMessage")&.text
-        error_code    = xml.at("errorCode")&.text
-
-        {error_message: error_message, error_code: error_code}
+        error_message = xml.at("errorMessage")&.text&.presence
+        error_code    = xml.at("errorCode")&.text&.presence&.upcase
       elsif is_json_response?(body)
         json = Oj.load(body)
         json.extend Hashie::Extensions::DeepFind
@@ -123,13 +167,11 @@ module AlmaApi
         # and sometimes the format is:
         #   {"web_service_result":{"errorList":{"error":{"errorMessage":"xxx","errorCode":"xxx"}}}}
         # so we use a deep find to find the first occurrence of "errorMessage" and "errorCode"
-        error_message = json.deep_find("errorMessage")
-        error_code    = json.deep_find("errorCode")
-
-        {error_message: error_message, error_code: error_code}
-      else
-        {error_message: nil, error_code: nil}
+        error_message = json.deep_find("errorMessage")&.presence
+        error_code    = json.deep_find("errorCode")&.presence
       end
+
+      [error_message, error_code]
     end
 
     def is_xml_response?(body)

data/lib/alma_api/configuration.rb

@@ -9,19 +9,26 @@ module AlmaApi
       cn: "https://api-cn.hosted.exlibrisgroup.cn/almaws/v1"   # China
     }.freeze
 
+    DEFAULT_GATEWAY  = GATEWAYS[:eu].freeze
     DEFAULT_FORMAT   = "json".freeze
     DEFAULT_LANGUAGE = "en".freeze
 
     attr_reader :api_key,
                 :base_url,
                 :default_format,
-                :language
+                :language,
+                :timeout
 
-    def initialize(api_key: nil, base_url: nil, default_format: nil, language: nil)
+    def initialize(api_key: nil)
+      # Set defaults. Passing nil to the setters will set the default value.
       self.api_key = api_key
-      self.base_url = base_url
-      self.default_format = default_format
-      self.language = language
+      self.base_url = nil
+      self.default_format = nil
+      self.language = nil
+      self.timeout = nil
+
+      # Yield self to allow block-style configuration.
+      yield(self) if block_given?
     end
 
     def api_key=(value)
@@ -30,11 +37,13 @@ module AlmaApi
 
     def base_url=(value)
       if value.is_a?(Symbol)
-        raise ArgumentError, "Invalid gateway: #{value}" unless GATEWAYS.keys.include?(value.to_sym)
+        raise ArgumentError, "Invalid gateway: #{value}" unless GATEWAYS.keys.include?(value)
 
         @base_url = GATEWAYS[value]
+      elsif value.is_a?(String)
+        @base_url = value.presence || DEFAULT_GATEWAY
       else
-        @base_url = value.presence || GATEWAYS[:eu]
+        @base_url = DEFAULT_GATEWAY
       end
     end
 
@@ -43,7 +52,11 @@ module AlmaApi
     end
 
     def language=(value)
-      @language = value.presence || DEFAULT_LANGUAGE
+      @language = value.presence&.to_s || DEFAULT_LANGUAGE
+    end
+
+    def timeout=(value)
+      @timeout = value.presence
     end
 
   end

data/lib/alma_api/version.rb

@@ -1,3 +1,3 @@
 module AlmaApi
-  VERSION = "1.0.2".freeze
+  VERSION = "2.0.0".freeze
 end

data/lib/alma_api.rb

@@ -15,7 +15,7 @@ module AlmaApi
   class Error < StandardError
     attr_reader :code
 
-    def initialize(message, code)
+    def initialize(message=nil, code=nil)
       @code = code.presence || DEFAULT_ERROR_CODE
       super(message.presence || DEFAULT_ERROR_MESSAGE)
     end
@@ -25,6 +25,8 @@ module AlmaApi
   class ServerError  < Error; end
   class LogicalError < Error; end
 
+  GENERAL_ERROR_MESSAGE = "Error occured while performing request. Check #cause for more details.".freeze
+
   GATEWAY_ERROR_CODES = [
     "GENERAL_ERROR",
     "UNAUTHORIZED",
@@ -39,9 +41,10 @@ module AlmaApi
   class << self
 
     def configure
-      configuration = Configuration.new
-      yield(configuration) if block_given?
-      Client.new(configuration)
+      warn "[DEPRECATION] `AlmaApi.configure` is deprecated. Please use `AlmaApi::Client.configure` instead."
+      client = Client.configure
+      yield(client.configuration) if block_given?
+      client
     end
 
     def validate_format!(format)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: alma_api
 version: !ruby/object:Gem::Version
-  version: 1.0.2
+  version: 2.0.0
 platform: ruby
 authors:
 - René Sprotte
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2024-01-15 00:00:00.000000000 Z
+date: 2024-02-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -118,7 +118,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.10
+rubygems_version: 3.4.19
 signing_key: 
 specification_version: 4
 summary: A Ruby client library for the Ex Libris Alma REST APIs