alma_api 2.0.1 → 2.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b21e33c3c303e5ea01c584595be071a745c0c1738004bf5c3d5c040e653e93ed
-  data.tar.gz: fcd35e87137dac29d4aabe35e17f5aad838cc90c27d652e05013f66fe731cecc
+  metadata.gz: e8e6d67ca8b1f7ee74336b896567b177697396868a733635334d78154078aa99
+  data.tar.gz: d75dee6ae68ff2bedce2e1c85938a7ca9087edc77bbfa0bb9175e76183017fd2
 SHA512:
-  metadata.gz: 8dab34fccec10fcb9c26e40782ada02fc5c511c0c3120730b4ff807055eca514cab07ed193a9f8ae8d04455a37da997dd50d4c0d16cdd60ec018bd7b23c241b8
-  data.tar.gz: 62a5f0cad8b8303c17cb014942268d3382e6cb3f5ad951aedf74d0aa5a12fb1b7656bccdeb205ffe37ab45a6f899775dd7e8dc3f2150ae85f1a2fe3a064bf7ff
+  metadata.gz: 5fff956ecfd7c325d41a69a78f0ffb8a42dc0ff3bd53a7e355153bed2e19f753d59ea43ba0bdb0def362233a76b5f92d03ca8984918cb862cf2c970c4f1a6ec0
+  data.tar.gz: e9bb33ce7580102d2ee4c8ee02fc483e2020e72d4d5d8c6940e11195305b7f84f62dda5a8405e5e6f86512601cd0d792c57e6b669e47d9911d18059e6ca0b106

data/README.md

@@ -28,7 +28,7 @@ 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).__
+__Note: There a some changes when upgrading from 1.x to 2.x. [Please read the section on upgrading below](#upgrading).__
 
 ### Quick example
 
@@ -60,14 +60,14 @@ 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 `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`
     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`
-    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`.
+    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.
 
     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).
 
@@ -94,7 +94,7 @@ With the configuration ready, you can create the client.
 ```ruby
 client = AlmaApi::Client.new(configuration)
 ```
-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.
+As a shortcut, you can call `AlmaApi::Client.configure` with a block to get the client instance. Note that each call to `AlmaApi::Client.configure` returns a new `AlmaApi::Client` instance.
 
 ```ruby
 client = AlmaApi::Client.configure do |config|
@@ -110,11 +110,11 @@ The client provides the following 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.
+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.
 
 #### Get remaining API calls
 
@@ -199,22 +199,23 @@ 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.
+For some errors, code may be `nil`.
 
 ### 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.
+If the Alma API responds with a `4xx` OR `5xx` HTTP status AND one of the following error codes, an `AlmaApi::GatewayError` is raised.
 
 `GENERAL_ERROR`, `UNAUTHORIZED`, `INVALID_REQUEST`, `PER_SECOND_THRESHOLD`, `DAILY_THRESHOLD`, `REQUEST_TOO_LARGE`, `FORBIDDEN`, `ROUTING_ERROR`
 
 Check the [the documentation here](https://developers.exlibrisgroup.com/alma/apis/#error) for more information about gateway errors.
 
-### 2. `AlmaApi::ServerError`
+### 3. `AlmaApi::ServerError`
 
-Any `5xx` HTTP status that does not result in an `AlmaApi::GatewayError` will be thrown as an `AlmaApi::ServerError`.
+Any `5xx` HTTP status that does not result in an `AlmaApi::GatewayError` will be raised as an `AlmaApi::ServerError`.
 
-### 3. `AlmaApi::LogicalError`
+### 4. `AlmaApi::LogicalError`
 
-Any `4xx` HTTP status that does not result in an `AlmaApi::GatewayError` will be thrown as an `AlmaApi::LogicalError`.
+Any `4xx` HTTP status that does not result in an `AlmaApi::GatewayError` will be raised as an `AlmaApi::LogicalError`.
 
 This is the most common error you will encounter and can be used to manage the control flow in your application.
 
@@ -247,7 +248,7 @@ As stated before this library uses [`faraday`](https://github.com/lostisland/far
 
 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.
+However, there is still 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, which you can use to manipulate the request before it is sent to Alma.
 
 ```ruby
 client.get("some/path") do |req|

data/lib/alma_api/client.rb

@@ -89,10 +89,15 @@ module AlmaApi
 
       # 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. The password must be url-encoded.
+      # authenticating a user.
+      #
+      # The password must be url-encoded. As there are different ways to encode
+      # spaces (%20 vs +), makre sure to use a method that encodes spaces as %20
+      # as this is what Alma seems to expect.
+      #
       # @see https://developers.exlibrisgroup.com/alma/apis/docs/users/UE9TVCAvYWxtYXdzL3YxL3VzZXJzL3t1c2VyX2lkfQ==/
       if (password = params.delete(:password) || params.delete("password")).present?
-        headers["Exl-User-Pw"] = CGI.escape(password)
+        headers["Exl-User-Pw"] = URI.encode_uri_component(password)
       end
 
       # Finally create and return the Faraday connection object.

data/lib/alma_api/version.rb

@@ -1,3 +1,3 @@
 module AlmaApi
-  VERSION = "2.0.1".freeze
+  VERSION = "2.0.2".freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: alma_api
 version: !ruby/object:Gem::Version
-  version: 2.0.1
+  version: 2.0.2
 platform: ruby
 authors:
 - René Sprotte
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2024-02-02 00:00:00.000000000 Z
+date: 2024-03-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport