{"id":13491733,"url":"https://github.com/wojtekmach/req","last_synced_at":"2025-05-13T16:06:26.673Z","repository":{"id":37439466,"uuid":"352386739","full_name":"wojtekmach/req","owner":"wojtekmach","description":"Req is a batteries-included HTTP client for Elixir.","archived":false,"fork":false,"pushed_at":"2025-03-28T19:52:37.000Z","size":1029,"stargazers_count":1184,"open_issues_count":57,"forks_count":130,"subscribers_count":12,"default_branch":"main","last_synced_at":"2025-04-19T21:15:56.291Z","etag":null,"topics":["elixir","http-client"],"latest_commit_sha":null,"homepage":"https://hexdocs.pm/req","language":"Elixir","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wojtekmach.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","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}},"created_at":"2021-03-28T16:59:50.000Z","updated_at":"2025-04-18T00:58:51.000Z","dependencies_parsed_at":"2023-02-17T05:00:40.796Z","dependency_job_id":"c6486fc0-e59e-4ecc-ba94-231d42b1a1df","html_url":"https://github.com/wojtekmach/req","commit_stats":{"total_commits":370,"total_committers":29,"mean_commits":"12.758620689655173","dds":"0.21621621621621623","last_synced_commit":"36fa23632e1e77299aea5cdd8d76e40203f1e982"},"previous_names":[],"tags_count":45,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wojtekmach%2Freq","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wojtekmach%2Freq/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wojtekmach%2Freq/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wojtekmach%2Freq/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wojtekmach","download_url":"https://codeload.github.com/wojtekmach/req/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250513380,"owners_count":21443200,"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":["elixir","http-client"],"created_at":"2024-07-31T19:00:59.725Z","updated_at":"2025-05-13T16:06:26.664Z","avatar_url":"https://github.com/wojtekmach.png","language":"Elixir","funding_links":[],"categories":["Elixir","HTTP"],"sub_categories":[],"readme":"# Req\n\n[![CI](https://github.com/wojtekmach/req/actions/workflows/ci.yml/badge.svg)](https://github.com/wojtekmach/req/actions/workflows/ci.yml)\n[![License](https://img.shields.io/hexpm/l/req.svg)](https://github.com/wojtekmach/req/blob/main/LICENSE.md)\n[![Version](https://img.shields.io/hexpm/v/req.svg)](https://hex.pm/packages/req)\n[![Hex Docs](https://img.shields.io/badge/documentation-gray.svg)](https://hexdocs.pm/req)\n\nReq is a batteries-included HTTP client for Elixir.\n\nWith just a couple lines of code:\n\n```elixir\nMix.install([\n  {:req, \"~\u003e 0.5.0\"}\n])\n\nReq.get!(\"https://api.github.com/repos/wojtekmach/req\").body[\"description\"]\n#=\u003e \"Req is a batteries-included HTTP client for Elixir.\"\n```\n\nwe get automatic response body decompression \u0026 decoding, following redirects, retrying on errors,\nand much more. Virtually all of the features are broken down into individual functions called\n_steps_. You can easily re-use and re-arrange built-in steps (see [`Req.Steps`] module) and\nwrite new ones.\n\n## Features\n\n  * An easy to use high-level API: [`Req.request/1`], [`Req.new/1`], [`Req.get!/2`], [`Req.post!/2`], etc.\n\n  * Extensibility via request, response, and error steps.\n\n  * Request body compression (via [`compress_body`] step)\n\n  * Automatic response body decompression (via [`compressed`] and [`decompress_body`] steps). Supports gzip, brotli, and zstd.\n\n  * Request body encoding. Supports urlencoded and multipart forms, and JSON. See [`encode_body`].\n\n  * Automatic response body decoding (via [`decode_body`] step.)\n\n  * Encode params as query string (via [`put_params`] step.)\n\n  * Setting base URL (via [`put_base_url`] step.)\n\n  * Templated request paths (via [`put_path_params`] step.)\n\n  * Basic, bearer, and `.netrc` authentication (via [`auth`] step.)\n\n  * Range requests (via [`put_range`]) step.)\n\n  * Use AWS V4 Signature (via [`put_aws_sigv4`]) step.)\n\n  * Request body streaming (by setting `body: enumerable`.)\n\n  * Response body streaming (by setting `into: fun | collectable | :self`.)\n\n  * Follows redirects (via [`redirect`] step.)\n\n  * Retries on errors (via [`retry`] step.)\n\n  * Raise on 4xx/5xx errors (via [`handle_http_errors`] step.)\n\n  * Verify response body against a checksum (via [`checksum`] step.)\n\n  * Basic HTTP caching (via [`cache`] step.)\n\n  * Easily create test stubs (see [`Req.Test`].)\n\n  * Running against a plug (via [`run_plug`] step.)\n\n  * Pluggable adapters. By default, Req uses [Finch] (via [`run_finch`] step.)\n\n## Usage\n\nThe easiest way to use Req is with [`Mix.install/2`] (requires Elixir v1.12+):\n\n```elixir\nMix.install([\n  {:req, \"~\u003e 0.5.0\"}\n])\n\nReq.get!(\"https://api.github.com/repos/wojtekmach/req\").body[\"description\"]\n#=\u003e \"Req is a batteries-included HTTP client for Elixir.\"\n```\n\nIf you want to use Req in a Mix project, you can add the above dependency to your `mix.exs`.\n\nHere's an example POST with JSON data:\n\n```elixir\niex\u003e Req.post!(\"https://httpbin.org/post\", json: %{x: 1, y: 2}).body[\"json\"]\n%{\"x\" =\u003e 1, \"y\" =\u003e 2}\n```\n\nYou can stream request body:\n\n```elixir\niex\u003e stream = Stream.duplicate(\"foo\", 3)\niex\u003e Req.post!(\"https://httpbin.org/post\", body: stream).body[\"data\"]\n\"foofoofoo\"\n```\n\nand stream the response body:\n\n```elixir\niex\u003e resp = Req.get!(\"http://httpbin.org/stream/2\", into: IO.stream())\n# output: {\"url\": \"http://httpbin.org/stream/2\", ...}\n# output: {\"url\": \"http://httpbin.org/stream/2\", ...}\niex\u003e resp.status\n200\niex\u003e resp.body\n%IO.Stream{}\n```\n\n(See [`Req`] module documentation for more examples of response body streaming.)\n\nIf you are planning to make several similar requests, you can build up a request struct with\ndesired common options and re-use it:\n\n```elixir\nreq = Req.new(base_url: \"https://api.github.com\")\n\nReq.get!(req, url: \"/repos/sneako/finch\").body[\"description\"]\n#=\u003e \"Elixir HTTP client, focused on performance\"\n\nReq.get!(req, url: \"/repos/elixir-mint/mint\").body[\"description\"]\n#=\u003e \"Functional HTTP client for Elixir with support for HTTP/1 and HTTP/2.\"\n```\n\nSee [`Req.new/1`] for more information on available options.\n\nVirtually all of Req's features are broken down into individual pieces - steps. Req works by running\nthe request struct through these steps. You can easily reuse or rearrange built-in steps or write new\nones. Importantly, steps are just regular functions. Here is another example where we append a request\nstep that inspects the URL just before requesting it:\n\n```elixir\nreq =\n  Req.new(base_url: \"https://api.github.com\")\n  |\u003e Req.Request.append_request_steps(\n    debug_url: fn request -\u003e\n      IO.inspect(URI.to_string(request.url))\n      request\n    end\n  )\n\nReq.get!(req, url: \"/repos/wojtekmach/req\").body[\"description\"]\n# output: \"https://api.github.com/repos/wojtekmach/req\"\n#=\u003e \"Req is a batteries-included HTTP client for Elixir.\"\n```\n\nCustom steps can be packaged into plugins so that they are even easier to use by others. See [Related Packages](#related-packages).\n\nHere is how they can be used:\n\n```elixir\nMix.install([\n  {:req, \"~\u003e 0.5.0\"},\n  {:req_easyhtml, \"~\u003e 0.1.0\"},\n  {:req_s3, \"~\u003e 0.2.3\"},\n  {:req_hex, \"~\u003e 0.2.0\"},\n  {:req_github_oauth, \"~\u003e 0.1.0\"}\n])\n\nreq =\n  (Req.new(http_errors: :raise)\n  |\u003e ReqEasyHTML.attach()\n  |\u003e ReqS3.attach()\n  |\u003e ReqHex.attach()\n  |\u003e ReqGitHubOAuth.attach())\n\nReq.get!(req, url: \"https://elixir-lang.org\").body[\".entry-summary h5\"]\n#=\u003e\n# #EasyHTML[\u003ch5\u003e\n#    Elixir is a dynamic, functional language for building scalable and maintainable applications.\n#  \u003c/h5\u003e]\n\nReq.get!(req, url: \"s3://ossci-datasets/mnist/t10k-images-idx3-ubyte.gz\").body\n#=\u003e \u003c\u003c0, 0, 8, 3, ...\u003e\u003e\n\nReq.get!(req, url: \"https://repo.hex.pm/tarballs/req-0.1.0.tar\").body[\"metadata.config\"][\"links\"]\n#=\u003e %{\"GitHub\" =\u003e \"https://github.com/wojtekmach/req\"}\n\nReq.get!(req, url: \"https://api.github.com/user\").body[\"login\"]\n# output:\n# paste this user code:\n#\n#   6C44-30A8\n#\n# at:\n#\n#   https://github.com/login/device\n#\n# open browser window? [Yn]\n# 15:22:28.350 [info] response: authorization_pending\n# 15:22:33.519 [info] response: authorization_pending\n# 15:22:38.678 [info] response: authorization_pending\n#=\u003e \"wojtekmach\"\n\nReq.get!(req, url: \"https://api.github.com/user\").body[\"login\"]\n#=\u003e \"wojtekmach\"\n```\n\nSee [`Req.Request`] module documentation for more information on low-level API, request struct, and developing plugins.\n\n## Configuration\n\nReq supports many configuration options, see [`Req.new/1`] for a full list and see each step for\nmore details. In particular, if you are looking for slightly lower level HTTP options such as\ntimeouts, pool sizes, and certificates, see the [`run_finch`] documentation.\n\n## Related Packages\n\nThere are many packages that extend the Req library. To get yours listed here, send a PR.\n\n  * [`req_easyhtml`]\n  * [`req_s3`]\n  * [`req_hex`]\n  * [`req_github_oauth`]\n  * [`curl_req`]\n  * [`http_cookie`]\n  * [`req_embed`]\n\n## Presentations\n\n  * [Req: A batteries-included HTTP client for Elixir - ElixirConf 2023, 2023-09-08](https://www.youtube.com/watch?v=owz2QacFuoQ \"ElixirConf 2023 - Wojtek Mach - Req - a batteries-included HTTP client for Elixir\")\n  * [Req: A batteries included HTTP client for Elixir - Elixir Kenya, 2022-08-26](https://www.youtube.com/watch?v=NxWgvHRN6mI \"Req: A batteries included HTTP client for Elixir\")\n\n## Acknowledgments\n\nReq is built on top of [Finch] and is inspired by [cURL], [Requests], [Tesla], and many other HTTP clients - thank you!\n\n## License\n\nCopyright (c) 2021 Wojtek Mach\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at [http://www.apache.org/licenses/LICENSE-2.0](http://www.apache.org/licenses/LICENSE-2.0)\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n\n[`Req.request/1`]:       https://hexdocs.pm/req/Req.html#request/1\n[`Req.new/1`]:           https://hexdocs.pm/req/Req.html#new/1\n[`Req.get!/2`]:          https://hexdocs.pm/req/Req.html#get!/2\n[`Req.post!/2`]:         https://hexdocs.pm/req/Req.html#post!/2\n[`Req`]:                 https://hexdocs.pm/req\n[`Req.Request`]:         https://hexdocs.pm/req/Req.Request.html\n[`Req.Steps`]:           https://hexdocs.pm/req/Req.Steps.html\n[`Req.Test`]:            https://hexdocs.pm/req/Req.Test.html\n\n[`auth`]:               https://hexdocs.pm/req/Req.Steps.html#auth/1\n[`cache`]:              https://hexdocs.pm/req/Req.Steps.html#cache/1\n[`compress_body`]:      https://hexdocs.pm/req/Req.Steps.html#compress_body/1\n[`compressed`]:         https://hexdocs.pm/req/Req.Steps.html#compressed/1\n[`decode_body`]:        https://hexdocs.pm/req/Req.Steps.html#decode_body/1\n[`decompress_body`]:    https://hexdocs.pm/req/Req.Steps.html#decompress_body/1\n[`encode_body`]:        https://hexdocs.pm/req/Req.Steps.html#encode_body/1\n[`redirect`]:           https://hexdocs.pm/req/Req.Steps.html#redirect/1\n[`handle_http_errors`]: https://hexdocs.pm/req/Req.Steps.html#handle_http_errors/1\n[`output`]:             https://hexdocs.pm/req/Req.Steps.html#output/1\n[`put_base_url`]:       https://hexdocs.pm/req/Req.Steps.html#put_base_url/1\n[`put_params`]:         https://hexdocs.pm/req/Req.Steps.html#put_params/1\n[`put_path_params`]:    https://hexdocs.pm/req/Req.Steps.html#put_path_params/1\n[`run_plug`]:           https://hexdocs.pm/req/Req.Steps.html#run_plug/1\n[`put_range`]:          https://hexdocs.pm/req/Req.Steps.html#put_range/1\n[`put_user_agent`]:     https://hexdocs.pm/req/Req.Steps.html#put_user_agent/1\n[`retry`]:              https://hexdocs.pm/req/Req.Steps.html#retry/1\n[`run_finch`]:          https://hexdocs.pm/req/Req.Steps.html#run_finch/1\n[`checksum`]:           https://hexdocs.pm/req/Req.Steps.html#checksum/1\n[`put_aws_sigv4`]:       https://hexdocs.pm/req/Req.Steps.html#put_aws_sigv4/1\n\n[Finch]: https://github.com/sneako/finch\n[cURL]: https://curl.se\n[Requests]: https://docs.python-requests.org/en/master/\n[Tesla]: https://github.com/elixir-tesla/tesla\n[`req_easyhtml`]: https://github.com/wojtekmach/req_easyhtml\n[`req_s3`]: https://github.com/wojtekmach/req_s3\n[`req_hex`]: https://github.com/wojtekmach/req_hex\n[`req_github_oauth`]: https://github.com/wojtekmach/req_github_oauth\n[`Mix.install/2`]: https://hexdocs.pm/mix/Mix.html#install/2\n[`curl_req`]: https://github.com/derekkraan/curl_req\n[`http_cookie`]: https://github.com/reisub/http_cookie\n[`req_embed`]: https://github.com/leandrocp/req_embed\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwojtekmach%2Freq","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwojtekmach%2Freq","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwojtekmach%2Freq/lists"}