{"id":21496768,"url":"https://github.com/mlibrary/alma_rest_client","last_synced_at":"2025-03-17T12:22:16.280Z","repository":{"id":44644372,"uuid":"332838723","full_name":"mlibrary/alma_rest_client","owner":"mlibrary","description":null,"archived":false,"fork":false,"pushed_at":"2022-09-26T20:44:43.000Z","size":68,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-01-23T22:12:29.134Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mlibrary.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-01-25T18:09:46.000Z","updated_at":"2022-01-07T15:27:58.000Z","dependencies_parsed_at":"2023-01-18T16:10:01.750Z","dependency_job_id":null,"html_url":"https://github.com/mlibrary/alma_rest_client","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlibrary%2Falma_rest_client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlibrary%2Falma_rest_client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlibrary%2Falma_rest_client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlibrary%2Falma_rest_client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mlibrary","download_url":"https://codeload.github.com/mlibrary/alma_rest_client/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244031056,"owners_count":20386534,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-23T16:18:40.286Z","updated_at":"2025-03-17T12:22:16.260Z","avatar_url":"https://github.com/mlibrary.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AlmaRestClient\n\nThis gem retrieves Alma data from the Alma API. It extends the HTTParty gem.\n\n## Minimal Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\nsource \"https://rubygems.pkg.github.com/mlibrary\" do\n  gem \"alma_rest_client\", \"~\u003e 2.0\"\nend\n```\n\nAnd then execute:\n```\n$ bundle install\n```\n\nOr install it yourself as:\n```\n$ gem install alma_rest_client\n```\n\nSet the API key.\n\nSet the following environment variables\n```\nALMA_API_KEY\n```\n\nOr directly configure it:\n```ruby\nAlmaRestClient.configure do |config|\n  config.alma_api_key = ENV.fetch(\"ENV_VAR_WITH_API_KEY\")\nend\n```\n\n## Usage\nAll of the following methods return a `Faraday::Response` object from Alma\n\n```ruby\n#all are instance methods\nclient = AlmaRestClient.client\n\n# Get method without options\nresponse = client.get('/users/soandso')\n\n# Get method with options\nresponse = client.get('/users/soandso/loans', query: {\"limit\" =\u003e 100, \"expand\" =\u003e \"renewable\"}\n\n#post method without options\nresponse = client.post('/users/soandso/loans/123958915158')\n\n#post method with options\nresponse = client.post('/users/soandso/loans/123958915158', query: {\"op\" =\u003e \"renew\"}, body: 'ruby_hash_or_array or string its expecting to receive')\n\n#put method\nresponse = client.put('/users/soandso', body: 'ruby_hash_or_array or json_body_string_alma_is_expecting_to_receive')\n\n```\n`get_all` method tries twice to get full list of results from Alma. This returns an AlmaRestClient::Response object which has a code, message, and parsed_response. The full list is of the form of a normal `AlmaRestClient#get` method, if there was a limit \"ALL\" option. `get_all` method uses keyword arguments. `:url` and `:record_key` are required arguments.\n\n```ruby\n#all are instance methods\nclient = AlmaRestClient.client\n\n#get_all without options\nresponse = client.get_all(url: '/users/soandso/loans', record_key: 'item_loan')\n\n#get_all with options; this method overwrites 'limit' and 'offset'\nresponse = client.get_all(url: '/users/soandso/loans', record_key: 'item_loan', query: {\"expand\" =\u003e \"renewable\"})\n```\n`get_report` method is used for working Alma Analytics reports. It takes the argument `:path` which is the path to the analytics report. It can take a block or no block.\n\nWhen no block is given to `get_report` it returns an `AlmaRestClient::Response` object which has a code, messsage, and parsed_response. The parsed response is an array of report rows. Each row element is a hash where the keys are the column names of the report. \n\nWhen a block is given, the block can work with a row of the report. Each row is a hash where the keys are the column names of the report. If it's successful it will return a successful `AlmaRestClient::Response` object.  \n\n\n```ruby\n#all are instance methods\nclient = AlmaRestClient.client\n\n#get_report\nresponse = client.get_report(path: '/shared/University of Michigan 01UMICH_INST/Reports/fake-data')\n\nmy_array = []\nresponse = client.get_report(path: '/shared/University of Michigan 01UMICH_INST/Reports/fake-data') do |row|\n  my_array.push(row)\nend\n\n#optional 'retries' parameter is for how many times to retry a page of the report. Default is 2.\nresponse = client.get_report(path: '/shared/University of Michigan 01UMICH_INST/Reports/fake-data', retries: 5)\n```\n## Configuration\n\n### Environment Variables\nConfiguration of the Alma API Key and the Alma host can be done with the following environment variables\n\n```\nALMA_API_KEY\nALMA_API_HOST\n```\n### Direct Configuration\nThe gem can be configured directly with this pattern:\n\n```ruby\nAlmaRestClient.configure do |config|\n  config.alma_api_key = ENV.fetch(\"ENV_VAR_WITH_API_KEY\")\nend\n```\nConfiguring directly overrides the environment variables. \n\n### Configuration Options\nBelow are the configuration options and their defaults:\n|Name|Description|Default Value|\n|---|---|---|\n|`alma_api_key`|The Alma API Key that has the appropriate permissions|`\"\"`|\n|`alma_api_host`|The base exlibris url | `https://api-na.hosted.exlibrisgroup.com`|\n| `http_adapter` | The http adapter for Faraday to use | `:httpx` |\n| `retry_options` | A hash of options for the [retry adapter for Faraday](https://github.com/lostisland/faraday-retry) | `{ max: 1, retry_statuses: [500] }` |\n\n## Using a custom Faraday connection object\n\nThe `AlmaRestClient::Client` object can be initialized with a `Faraday::Connection` object like so:\n```ruby\nconn = Faraday.new do\n# Whatever special setting you want\nend\nAlmaRestClient.new(conn)\n```\nThe `adapter` will still be set to whatever is in `http_adapter`. The `retry` adapter must also be configured in the configuration options.\n\n## Rspec Test Helpers\nThis gem includes `rspec` test helpers. They require the [Webmock library](https://github.com/bblimke/webmock). To use them put the following in your `spec_helper.rb`\n\n```ruby\nrequire \"alma_rest_client\"\nrequire \"webmock/rspec\"\nrequire \"httpx/adapters/webmock\"\n\nRspec.configure do |config|\n  include AlmaRestClient::Test::Helpers\n# ....\nend\n```\n\nThis will give you the following stubs:\n```\nstub_alma_get_request(url:, input:, output:, status:, query:, no_return)\nstub_alma_post_request(url:, input:, output:, status:, query:, no_return)\nstub_alma_put_request(url:, input:, output:, status:, query:, no_return)\nstub_alma_delete_request(url:, input:, output:, status:, query:, no_return)\n```\nThe parameters are described below.\n|parameter| description | default|\n|---|---|---|\n|`url`| The path to the api endpoint that you would use with the actual client | (required) |\n|`input`| The body of the input given to the  request | `nil` |\n|`output`| The body the stubbed request should return | `nil` |\n|`status`| The status the stubbed request should return | `200` |\n|`query`| The query parameters that should be part of the stubbed request | `nil` |\n|`no_return`| This is for when you want to add to the stub, like `to_raise`. If this is not nil, then `output` will be ignored. | `nil` |\n\n\n## How to Contribute\n\nClone the repository and cd into it\n```\n$ git clone git@github.com:mlibrary/alma_rest_client.git\n$ cd alma_rest_client\n```\n\nCopy `.env-example` to `.env`\n```\n$ cp .env-example .env\n```\n\nEdit `.env` Replace the value for `ALMA_API_KEY` with a real key with appropriate permissions\n\nBuild the image\n```\n$ docker-compose build\n```\n\nInstall the gems\n```\n$ docker-compose run --rm web bundle install\n```\n\n\nRun the tests\n```\n$ docker-compose run --rm web bundle exec rspec\n```\n\nTo run the gem in irb\n```\n$ docker-compose run --rm web bundle exec irb\nirb\u003e client = AlmaRestClient.client\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmlibrary%2Falma_rest_client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmlibrary%2Falma_rest_client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmlibrary%2Falma_rest_client/lists"}