{"id":21496559,"url":"https://github.com/mlibrary/handle_rest","last_synced_at":"2025-04-23T15:21:49.570Z","repository":{"id":8457153,"uuid":"58476560","full_name":"mlibrary/handle_rest","owner":"mlibrary","description":"ruby interface to handle REST api","archived":false,"fork":false,"pushed_at":"2024-01-12T14:29:26.000Z","size":110,"stargazers_count":2,"open_issues_count":18,"forks_count":2,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-03-30T00:51:13.439Z","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":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-05-10T16:22:28.000Z","updated_at":"2022-03-17T14:45:05.000Z","dependencies_parsed_at":"2022-08-07T04:16:34.585Z","dependency_job_id":null,"html_url":"https://github.com/mlibrary/handle_rest","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlibrary%2Fhandle_rest","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlibrary%2Fhandle_rest/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlibrary%2Fhandle_rest/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlibrary%2Fhandle_rest/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mlibrary","download_url":"https://codeload.github.com/mlibrary/handle_rest/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250457803,"owners_count":21433738,"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:17:11.663Z","updated_at":"2025-04-23T15:21:49.525Z","avatar_url":"https://github.com/mlibrary.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Ruby Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://github.com/testdouble/standard)\n![CI](https://github.com/mlibrary/handle_rest/actions/workflows/ci.yml/badge.svg)\n\n# Handle Rest\n\nRuby interface to the [CNRI Handle System](http://handle.net/) REST API.  The\nCNRI Handle Server provides a DNS-like method of providing persistent URLs to\nresources.  The REST API is available from Handle Server 8.0 onwards. The\n[HANDLE.NET Technical Manual](http://www.handle.net/tech_manual/HN_Tech_Manual_8.pdf) \ndocuments the REST API.\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n    gem 'handle_rest'\n\nAnd then execute:\n\n    $ bundle\n\nOr install it yourself as:\n\n    $ gem install handle_rest\n\n## Usage\n\n```ruby\nrequire 'handle_rest'\n\n# Set up the handle service connection\nhandle_service = HandleService.new(url: 'https://hdl.example.com:8000/api/handles',\n                                   user: '300:0.NA/PREFIX', \n                                   password: 'secret')\n\n# Set up the service to add the admin value line to all new handles\nadmin = Identity.from_s('300:0.NA/PREFIX')\nadmin_value = AdminValue.new(admin.index, AdminPermissionSet.new, admin.handle)\nadmin_value_line = ValueLine.new(100, admin_value)\nservice = Service.new([admin_value_line], handle_service)\n\n# Set up the URL service to store the URL at index 1\nurl_service = UrlService.new(1, service)\n\n# Create a handle with a URL\nurl_service.set('PREFIX/Suffix', 'http://example.com')\n\n# Retrieve the URL from the handle\nputs url_service.get('PREFIX/Suffix')\n\n# Update the URL of the handle\nurl_service.set('PREFIX/Suffix', 'https://www.example.com')\n\n# Retrieve the new URL from the handle\nputs url_service.get('PREFIX/Suffix')\n\n# Delete the handle\nservice.delete(Handle.from_s('PREFIX/Suffix'))\n```\n\n## Running the integration tests\n\nBy default rspec will not run the integration tests, because they require a test handle server.\nIf you have a test handle server available, set the following environment variables:\n\n```bash\n# Set this environment variable to run the integration tests\nINTEGRATION=1\n# Set to the URL for the test handle server\nHS_REST_URL=https://localhost:8000/api/handles/\n# Set to a homed prefix for the test handle server (including the trailing '/')\nHS_PREFIX=9999/\n# Set to appropriate credentials for a user that can create handles in the \n# given prefix. Currently, the API only supports password ('secret key')\n# authentication.\nHS_USER=300:9999/ADMIN\nHS_SECKEY=password\n# Set to 0 if the test handle server has a self-signed or otherwise invalid SSL\n# certificate\nHS_SSL_VERIFY=0\n\nexport INTEGRATION HS_REST_URL HS_USER HS_SECKEY HS_SSL_VERIFY\n```\n\n### Setting up a test handle server\n\n* Ensure java is installed\n* Download and unpack [the handle server](http://handle.net/download_hnr.html)\n* Follow the installation instructions from Section 3 \"Installing and Running a Handle Server\" from [the technical manual](http://www.handle.net/tech_manual/HN_Tech_Manual_8.pdf) up through section 3.4 \"Running the Setup Program\". Do NOT try to home a prefix with the handle admin tool (section 3.5), since this is only a test server.\n\nNext, manually home a test prefix and add an administrative user. This example\nuses `9999` as the prefix and `9999/ADMIN` as the administrative user, but you\ncan use whatever you want so long as it's consistent.\n\n* Set `server_admins` and `replication_admins` in `config.dct` to `300:9999/ADMIN`\n* Set `auto_homed_prefixes` in `config.dct` to `0.NA/9999`\n* Run `hdl-dbtool $HS_HOME` \n* Add a homed test prefix, `0.NA/9999`\n* Create a handle for an administrative user, `9999/ADMIN`, with values as follows:\n  * index 100, type `HS_ADMIN`, data type admin info, with admin ID handle `9999/ADMIN`, admin ID index 200, and all permissions selected\n  * index 200, type `HS_VLIST`, data type reference list, and one value: handle `9999/ADMIN`, index `300`\n  * index 300, type `HS_SECKEY`, data type string, set to the password you want to use for the administrative user (warning: this is stored in plain text in the database)\n* Start the handle server: `hdl-server $HS_HOME`\n\n### Containers\n\n#### docker-compose\n\nYou may also run the integration tests using docker-compose. To generate the docker-compose.yml file using the environment variables defined in the .env file run the yml-envsubst.sh shell script in the bin directory.\n```bash\n./bin/yml-envsubst.sh docker-compose.yml\n```\nThe docker-compose.yml file will pull images from the ${GITHUB_USER} account but first you'll need to create them using the build-image.sh and push-image.sh shell scripts in the bin directory.\n```bash\n./bin/build-image.sh ./image/mysql\n./bin/push-image.sh ./image/mysql\n./bin/build-image.sh ./image/ihs-handle-server\n./bin/push-image.sh ./image/ihs-handle-server\n./bin/build-image.sh .\n./bin/push-image.sh .\n```\nThe push-image.sh shell script will use the ${GITHUB_WRITE_PACKAGES_TOKEN} from the shell environment which must have write packages permission for the ${GITHUB_USER}. To run the tests use docker-compose up.\n```bash\ndocker-compose up\n```\nWhen the test finish you'll have to `ctrl-c` to interrupt and stop the services and then run docker-compose down to tidy things up.\n```bash\ndocker-compose down --remove-orphans\n```\n#### docker kubernetes\nYou may also run the integration tests in your Docker Desktop Kubernetes cluster. You'll have to generate the kubernetes manifest using the yml-envsubst.sh shell script in the bin directory against the *.yml.envsubst files in the kube/docker-desktop directory.  For example:\n```bash\n./bin/yml-envsubst.sh ./kube/docker-desktop/po/spec.yml\n```\n\nNote: ./kube/docker-desktop/secret/github-packages-read.yml manifest uses ${GITHUB_PACKAGES_READ} environment variable which is generated from the\n```bash\nexport GITHUB_PACKAGES_READ=`echo \"${GITHUB_USER}:${GITHUB_READ_PACKAGES_TOKEN}\" | base64`\n````\ninside the yml-envsubst.sh shell script. The ${GITHUB_READ_PACKAGES_TOKEN} must have read packages permission for the ${GITHUB_USER}.\n\nOnce you generate all the manifest use `kubectl apply` to populate your desktop cluster, for example:\n```bash\nkubectl apply -f ./kube/docker-desktop/secret/github-packages-read.yml\n```\nYou'll need to `kubectl exec` into pod/spec to manually run the specs.\n```bash\nkubectl exec -it pod/spec -- bash\n```\nthen\n```bash\nbundle exec rake\n```\nNot the prettiest implementation of containers but all you need is docker, kubectl and bash which is something.\n\n## Contributing\n\n1. Fork it\n2. Create your feature branch (`git checkout -b my-new-feature`)\n3. Commit your changes (`git commit -am 'Add some feature'`)\n4. Push to the branch (`git push origin my-new-feature`)\n5. Create new Pull Request\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmlibrary%2Fhandle_rest","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmlibrary%2Fhandle_rest","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmlibrary%2Fhandle_rest/lists"}