{"id":27405961,"url":"https://github.com/jzeni/restool","last_synced_at":"2025-04-14T06:16:21.147Z","repository":{"id":48626644,"uuid":"222121272","full_name":"jzeni/restool","owner":"jzeni","description":"Turn your API and its responses into Ruby interfaces.","archived":false,"fork":false,"pushed_at":"2025-04-14T01:51:49.000Z","size":89,"stargazers_count":6,"open_issues_count":2,"forks_count":2,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-14T02:35:11.596Z","etag":null,"topics":["api-client","http-client","rest-api","rest-client","ruby","ruby-on-rails"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jzeni.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":"2019-11-16T15:46:04.000Z","updated_at":"2025-02-19T13:41:03.000Z","dependencies_parsed_at":"2022-09-03T08:31:05.096Z","dependency_job_id":null,"html_url":"https://github.com/jzeni/restool","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jzeni%2Frestool","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jzeni%2Frestool/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jzeni%2Frestool/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jzeni%2Frestool/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jzeni","download_url":"https://codeload.github.com/jzeni/restool/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248811902,"owners_count":21165344,"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":["api-client","http-client","rest-api","rest-client","ruby","ruby-on-rails"],"created_at":"2025-04-14T06:16:19.552Z","updated_at":"2025-04-14T06:16:20.865Z","avatar_url":"https://github.com/jzeni.png","language":"Ruby","readme":"# Restool\n\nMake HTTP requests and handle their responses using simple method calls. Restool turns your HTTP API and its responses into Ruby interfaces.\n\nUse a declarative approach to call any API and decouple from their responses using a custom transformation.\n\n[![Gem Version](https://badge.fury.io/rb/restool.png)](http://badge.fury.io/rb/restool)\n[![CircleCI build status](https://circleci.com/gh/jzeni/restool.svg?style=shield)](https://circleci.com/gh/jzeni/restool/tree/master)\n[![Travis Build Status](https://travis-ci.org/jzeni/restool.svg?branch=master)](https://travis-ci.org/jzeni/restool)\n[![Code Climate](https://codeclimate.com/github/jzeni/restool.svg)](https://codeclimate.com/github/jzeni/restool)\n\n\n## Installation\n\nAdd the following line to Gemfile: `gem 'restool', '~\u003e 1'` and run bundle install from your shell.\n\nTo install the gem manually from your shell, run: `gem install restool`\n\n## Usage\nDefine the API endpoint and the response in a YML or JSON file:\n```\n# config/restool.yml\n\nservices:\n  - name: github_api\n    url: https://api.github.com\n    operations:\n      - name: get_repos\n        path: /users/:username/repos\n        method: get\n        response:\n          - key: id\n            metonym: identifier\n            type: integer\n          - key: full_name\n            type: string\n          - key: owner\n            type: owner\n\n    representations:\n      owner:\n        - key: login\n          metonym: username  # optional\n          type: string\n        - key: url\n          type: string\n```\n\nCreate the service object passing a response handler block, which will be automatically executed for each response:\n```\nrequire 'restool'\n\nremote_service = Restool.create('github_api') do |response, code|\n                  raise MyServiceError.new(response) unless code.to_i == 200\n\n                  JSON(response)\n                 end\n```\n\nUse the `remote_service` object to make calls:\n```\nuri_params   = [:jzeni]\nparams       = { sort: :created, direction: :desc }\n\nrepositories = remote_service.get_repos(uri_params, params)\n```\nAnd that's it!\n\nThe response object will define a method for each attribute of the response, with the same name or with the `metonym` name if given:\n\n```\nfirst_repository = repositories.first\n\nid               = first_repository.id\nfull_name        = first_repository.full_name\nowner_username   = first_repository.owner.username\nowner_url        = first_repository.owner.url\n\nraw_response     = first_repository._raw   # full raw response\n```\n\nIf you prefer to work with the raw responses (JSON) you should not define the `response` parameter in the operation configuration.\n\nSome important aspects:\n- Missing keys in the response but present in the representation will have a `nil` value in the converted response object.\n- The method `._raw` returns the response as it was returned by the response block, including attributes that might not be in the response representation.\n- If the response is an array you cannot call `._raw` directly, instead call `._raw` for each element.\n\n### Element types\n\nThe available types are:\n- string\n- integer\n- decimal\n- boolean\n\nRestool will parse the values to the given type for you.\n\n## More examples\n\n```\n# request with uri params, body params and header params\nremote_service.example_operation([uri_param_1, uri_param_2, ..., uri_param_n],\n                                 { param_name: value },\n                                 { header_name: :value })\n\n# request with body params and header params\nremote_service.example_operation({ param_name: value }, { header_name: :value })\n\n# request with header params and without body params\nremote_service.example_operation({}, { header_name: :value })\n\n# request only with body params\nremote_service.example_operation({ param_name: value })\n```\nSee other real examples in the examples directory\n\n## Additional features\n\n\n### Basic authentication\n```\nservices:\n  - name: example_api\n    url: http://example.api\n    basic_auth:\n      user: ...\n      password: ...\n    ...\n```\n\nor pass the credentials when creating the service:\n```\nopts = { basic_auth: { user: 'my_user', password: ENV['GITHUB_API_PASSWORD'] } }\n\nremote_service = Restool.create('github_api', opts) do |response, code|\n```\n\n### Logging\n```\nrequire \"logger\"\n\nmy_logger = Logger.new(STDOUT)  # or Logger.new(\"/path/to/my.log\")\n\nremote_service = Restool.create('github_api', logger: my_logger) do |response, code|\n                   ...\n                 end\n```\n\n### Debugging\n```\nremote_service = Restool.create('github_api', debug: true) do |response, code|\n                   ...\n                 end\n```\n\n### Timeout\n```\nservices:\n  - name: example_api\n    url: http://example.api\n    timeout: 20 #seconds\n    ...\n```\n\n### Get the response header\n```\nremote_service = Restool.create('github_api') do |response, code, header|\n                   ...\n                 end\n```\n\n\n### Read config\n\n```\nconfiguration = Restool::Settings::Loader.load('github_api')\n\nservice_name = configuration.service.name\n```\n\n\n## Multiple services\n\nYou can define multiple services, each one in a different file. These files should be placed in a `config/restool/` directory.\n\nFor instance, for the Github API we could have used `config/restool/github.json` or `config/restool/github_api.yml` instead of `config/restool.yml`.\n\n## Multipart\n\nThis gem currently does not support multipart requests\n\n# Questions?\n\nIf you have any question or doubt regarding Restool you can:\n- create an issue\n- [open a question on Stackoverflow](http://stackoverflow.com/questions/ask?tags=restool) with tag\n[restool](http://stackoverflow.com/questions/tagged/restool)\n\n# Contributing\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\n# Changelog (last)\n\n# 1.0.9\n\n* Fix Type parsing\n\n## 1.0.8\n\n* Fix compatibility problem with Ruby 1.9\n\n## 1.0.6\n\n* Refactor dev dependencies\n\n\n# Licence\nThis software is licensed under the MIT license.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjzeni%2Frestool","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjzeni%2Frestool","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjzeni%2Frestool/lists"}