{"id":15405200,"url":"https://github.com/fnando/aitch","last_synced_at":"2025-04-15T21:42:38.206Z","repository":{"id":56574293,"uuid":"9738251","full_name":"fnando/aitch","owner":"fnando","description":"A simple HTTP client.","archived":false,"fork":false,"pushed_at":"2023-11-20T18:22:49.000Z","size":159,"stargazers_count":21,"open_issues_count":0,"forks_count":2,"subscribers_count":5,"default_branch":"main","last_synced_at":"2024-04-29T11:20:24.125Z","etag":null,"topics":["http-client","ruby"],"latest_commit_sha":null,"homepage":null,"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/fnando.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["fnando"],"custom":["https://www.paypal.me/nandovieira/🍕"]}},"created_at":"2013-04-29T00:09:34.000Z","updated_at":"2024-06-19T15:24:55.852Z","dependencies_parsed_at":"2024-06-19T15:39:16.992Z","dependency_job_id":null,"html_url":"https://github.com/fnando/aitch","commit_stats":{"total_commits":112,"total_committers":2,"mean_commits":56.0,"dds":0.2321428571428571,"last_synced_commit":"04c84c7927961a02a91178a724166f7b4cd8e3e9"},"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fnando%2Faitch","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fnando%2Faitch/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fnando%2Faitch/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fnando%2Faitch/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fnando","download_url":"https://codeload.github.com/fnando/aitch/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":232651120,"owners_count":18555934,"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":["http-client","ruby"],"created_at":"2024-10-01T16:15:24.899Z","updated_at":"2025-01-05T23:04:33.822Z","avatar_url":"https://github.com/fnando.png","language":"Ruby","readme":"# Aitch\n\n[![Tests](https://github.com/fnando/aitch/actions/workflows/tests.yml/badge.svg)](https://github.com/fnando/aitch/actions/workflows/tests.yml)\n[![Code Climate](https://codeclimate.com/github/fnando/aitch/badges/gpa.svg)](https://codeclimate.com/github/fnando/aitch)\n[![Gem Version](https://img.shields.io/gem/v/aitch.svg)](https://rubygems.org/gems/aitch)\n[![Gem Downloads](https://img.shields.io/gem/dt/aitch.svg)](https://rubygems.org/gems/aitch)\n\nA simple HTTP client.\n\nFeatures:\n\n- Supports Gzip|Deflate response\n- Automatically parses JSON, HTML and XML responses\n- Automatically follows redirect\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem \"aitch\"\n```\n\nAnd then execute:\n\n    $ bundle\n\nOr install it yourself as:\n\n    $ gem install aitch\n\n## Usage\n\n### Configuration\n\nThese are the default settings:\n\n```ruby\nAitch.configure do |config|\n  # Set request timeout.\n  config.timeout = 5\n\n  # Set default headers.\n  config.default_headers = {}\n\n  # Set follow redirect.\n  config.follow_redirect = true\n\n  # Set redirection limit.\n  config.redirect_limit = 5\n\n  # Set the user agent.\n  config.user_agent = \"Aitch/0.0.1 (http://rubygems.org/gems/aitch)\"\n\n  # Set the logger.\n  config.logger = nil\n\n  # Set the base url.\n  config.base_url = nil\nend\n```\n\n### Requests\n\nPerforming requests:\n\n```ruby\nresponse = Aitch.get(\"http://example.org\", params, headers, options)\n           Aitch.post(\"http://example.org\", params, headers, options)\n           Aitch.put(\"http://example.org\", params, headers, options)\n           Aitch.patch(\"http://example.org\", params, headers, options)\n           Aitch.delete(\"http://example.org\", params, headers, options)\n           Aitch.options(\"http://example.org\", params, headers, options)\n           Aitch.trace(\"http://example.org\", params, headers, options)\n           Aitch.head(\"http://example.org\", params, headers, options)\n```\n\nYou can also use a DSL.\n\n```ruby\nresponse = Aitch.get do\n  url \"http://simplesideias.com.br\"\n  headers Authorization: \"Token token=abc\"\n  options follow_redirect: false\n  params a: 1, b: 2\nend\n```\n\nFinally, you can use keyword arguments:\n\n```ruby\nAitch.get(\n  url: \"http://example.org\",\n  params: {a: 1, b: 2},\n  headers: {Authorization: \"Token token=abc\"},\n  options: {follow_redirect: false}\n)\n```\n\n### Response\n\nThe response object:\n\n```ruby\nresponse.html?\nresponse.xml?\nresponse.json?\nresponse.content_type\nresponse.headers\nresponse.location\nresponse.success?         # status \u003e= 200 \u0026\u0026 status \u003c= 399\nresponse.redirect?        # status 3xx\nresponse.error?           # status 4xx or 5xx\nresponse.error            # response error\nresponse.body             # returned body\nresponse.data             # Parsed response body\n```\n\n#### Parsing JSON, XML and HTML with Nokogiri\n\nIf your response is a JSON, XML or a HTML content type, we'll automatically\nconvert the response into the appropriate object.\n\n```ruby\nresponse = Aitch.get(\"http://simplesideias.com.br\")\n\nresponse.data.class\n#=\u003e Nokogiri::HTML::Document\n\nresponse.data.css(\"h1\").size\n#=\u003e 69\n\nresponse = Aitch.get(\"http://simplesideias.com.br/feed\")\n\nresponse.data.class\n#=\u003e Nokogiri::XML::Document\n\nresponse.data.css(\"item\").size\n#=\u003e 10\n\nresponse = Aitch.get(\"https://api.github.com/users/fnando\")\nresponse.data.class\n#=\u003e Hash\n\nresponse.data[\"login\"]\n#=\u003e fnando\n```\n\n### Following redirects\n\nThe configuration:\n\n```ruby\nAitch.configure do |config|\n  config.follow_redirect = true\n  config.redirect_limit = 10\nend\n```\n\nThe request:\n\n```ruby\nAitch.get(\"http://example.org\")\n```\n\nIf the redirect limit is exceeded, then the `Aitch::TooManyRedirectsError`\nexception is raised.\n\n### Basic auth\n\nSetting basic auth credentials:\n\n```ruby\nresponse = Aitch.get do\n  url \"http://restrict.example.org/\"\n  options user: \"john\", password: \"test\"\nend\n```\n\n### Setting custom headers\n\n```ruby\nAitch.get do\n  url \"http://example.org\"\n  headers \"User-Agent\" =\u003e \"MyBot/1.0.0\"\nend\n```\n\nThe header value can be a callable object.\n\n```ruby\nAitch.configure do |config|\n  config.default_headers = {\n    \"Authorization\" =\u003e -\u003e { \"Token token=#{ENV.fetch(\"API_TOKEN\")}\" }\n  }\nend\n```\n\n### Creating namespaced requests\n\nSometimes you don't want to use the global settings (maybe you're building a\nlib). In this case, you can instantiate the namespace.\n\n```ruby\nRequest = Aitch::Namespace.new\nRequest.configure do |config|\n  config.user_agent = \"MyLib/1.0.0\"\nend\n\nRequest.get(\"http://example.org\")\n```\n\n### Validating responses\n\nWhen you know the kind of response you're expecting, you can validate it by\nspecifying the `expect` option.\n\n```ruby\nAitch.get do\n  url \"http://example.org\"\n  options expect: 200\nend\n```\n\nIf this request receives anything other than `200`, it will raise a\n`Aitch::StatusCodeError` exception.\n\n```\nExpect(200 OK) \u003c=\u003e Actual(404 Not Found)\n```\n\nYou can also provide a list of accepted statuses, like `expect: [200, 201]`.\n\n### Response Parsers\n\nYou can register new response parsers by using\n`Aitch::ResponseParser.register(name, parser)`, where parser must implement the\nmethods `match?(content_type)` and `load(response_body)`. This is how you could\nload CSV values.\n\n```ruby\nrequire \"csv\"\n\nmodule CSVParser\n  def self.type\n    :csv\n  end\n\n  def self.match?(content_type)\n    content_type.to_s =~ /csv/\n  end\n\n  def self.load(source)\n    CSV.parse(source.to_s)\n  end\nend\n\nAitch::ResponseParser.prepend(:csv, CSVParser)\n```\n\nThe default behavior is returning the response body. You can replace it as the\nfollowing:\n\n```ruby\nmodule DefaultParser\n  def self.type\n    :default\n  end\n\n  def self.match?(content_type)\n    true\n  end\n\n  def self.load(source)\n    source.to_s\n  end\nend\n\n# You should use append here, to ensure\n# that is that last parser on the list.\nAitch::ResponseParser.append(:default, DefaultParser)\n```\n\nAitch comes with response parsers for HTML, XML and JSON.\n\nBy default, the JSON parser will be `JSON`. To set it to something else, use\n`Aitch::ResponseParser::JSONParser.engine`.\n\n```ruby\nrequire \"oj\"\nAitch::ResponseParser::JSONParser.engine = Oj\n```\n\n### Setting the base url\n\nWhen you're creating a wrapper for an API, usually the hostname is the same for\nthe whole API. In this case, you can avoid having to pass it around all the time\nby setting `Aitch::Configuration#base_url`. This option is meant to be used when\nyou instantiate a new namespace.\n\n```ruby\nClient = Aitch::Namespace.new\n\nClient.configure do |config|\n  config.base_url = \"https://api.example.com\"\nend\n\nClient.get(\"/users\")\n```\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","funding_links":["https://github.com/sponsors/fnando","https://www.paypal.me/nandovieira/🍕"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffnando%2Faitch","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffnando%2Faitch","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffnando%2Faitch/lists"}