req: HTTP client library

[ bsd3, library, network, web ] [ Propose Tags ]

HTTP client library.


[Skip to Readme]
Versions [RSS] [faq] 0.1.0, 0.2.0, 0.3.0, 0.3.1, 0.4.0, 0.5.0, 1.0.0, 1.1.0, 1.2.0, 1.2.1, 2.0.0, 2.0.1, 2.1.0, 3.0.0, 3.1.0, 3.2.0, 3.3.0, 3.4.0, 3.5.0, 3.6.0, 3.7.0, 3.8.0, 3.9.0, 3.9.1, 3.9.2
Change log CHANGELOG.md
Dependencies aeson (>=0.9 && <3), authenticate-oauth (>=1.5 && <1.8), base (>=4.13 && <5.0), blaze-builder (>=0.3 && <0.5), bytestring (>=0.10.8 && <0.12), case-insensitive (>=0.2 && <1.3), connection (>=0.2.2 && <0.4), exceptions (>=0.6 && <0.11), http-api-data (>=0.2 && <0.5), http-client (==0.7.*), http-client-tls (>=0.3.2 && <0.4), http-types (>=0.8 && <10.0), modern-uri (==0.3.*), monad-control (==1.0.*), mtl (>=2.0 && <3.0), retry (>=0.8 && <0.10), template-haskell (>=2.14 && <2.18), text (>=0.2 && <1.3), time (>=1.2 && <1.13), transformers (>=0.4 && <0.6), transformers-base, unliftio-core (>=0.1.1 && <0.3) [details]
License BSD-3-Clause
Author Mark Karpov <markkarpov92@gmail.com>
Maintainer Mark Karpov <markkarpov92@gmail.com>
Category Network, Web
Home page https://github.com/mrkkrp/req
Bug tracker https://github.com/mrkkrp/req/issues
Source repo head: git clone https://github.com/mrkkrp/req.git
Uploaded by mrkkrp at 2021-10-13T08:35:04Z
Distributions Arch:3.9.1, Fedora:3.9.0, LTSHaskell:3.9.0, NixOS:3.9.0, Stackage:3.9.2
Downloads 19459 total (674 in the last 30 days)
Rating 2.5 (votes: 9) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Hackage Matrix CI
Docs available [build log]
Last success reported on 2021-10-13 [all 1 reports]

Modules

[Index] [Quick Jump]

Manual Flags

NameDescriptionDefault
dev

Turn on development settings.

Disabled
Automatic Flags
NameDescriptionDefault

Use -f <flag> to enable a flag, or -f -<flag> to disable that flag. More info

Downloads

Maintainer's Corner

For package maintainers and hackage trustees

Candidates


Readme for req-3.9.2

[back to package description]

Req

License BSD3 Hackage Stackage Nightly Stackage LTS CI

{-# LANGUAGE OverloadedStrings #-}

module Main (main) where

import Control.Monad.IO.Class
import Data.Aeson
import Network.HTTP.Req

main :: IO ()
-- You can either make your monad an instance of 'MonadHttp', or use
-- 'runReq' in any IO-enabled monad without defining new instances.
main = runReq defaultHttpConfig $ do
  let payload =
        object
          [ "foo" .= (10 :: Int),
            "bar" .= (20 :: Int)
          ]
  -- One function—full power and flexibility, automatic retrying on timeouts
  -- and such, automatic connection sharing.
  r <-
    req
      POST -- method
      (https "httpbin.org" /: "post") -- safe by construction URL
      (ReqBodyJson payload) -- use built-in options or add your own
      jsonResponse -- specify how to interpret response
      mempty -- query params, headers, explicit port number, etc.
  liftIO $ print (responseBody r :: Value)

Req is an HTTP client library that attempts to be easy-to-use, type-safe, and expandable.

“Easy-to-use” means that the library is designed to be beginner-friendly so it's simple to add to your monad stack, intuitive to work with, well-documented, and does not get in your way. Doing HTTP requests is a common task and a Haskell library for this should be approachable and clear to beginners, thus certain compromises were made. For example, one cannot currently modify ManagerSettings of the default manager because the library always uses the same implicit global manager for simplicity and maximal connection sharing. There is a way to use your own manager with different settings, but it requires more typing.

“Type-safe” means that the library tries to eliminate certain classes of errors. For example, we have correct-by-construction URLs; it is guaranteed that the user does not send the request body when using methods like GET or OPTIONS, and the amount of implicit assumptions is minimized by making the user specify their intentions in an explicit form. For example, it's not possible to avoid specifying the body or the method of a request. Authentication methods that assume HTTPS force the user to use HTTPS at the type level.

“Expandable” refers to the ability to create new components without having to resort to hacking. For example, it's possible to define your own HTTP methods, create new ways to construct the body of a request, create new authorization options, perform a request in a different way, and create your own methods to parse a response.

The library uses the following mature packages under the hood to guarantee you the best experience:

It is important to note that since we leverage well-known libraries that the whole Haskell ecosystem uses, there is no risk in using Req. The machinery for performing requests is the same as with http-conduit and Wreq. The only difference is the API.

The following packages are designed to be used with Req:

  • req-conduit—support for streaming request and response bodies in constant memory.

If you happen to have written a package that adds new features to Req, please submit a PR to include it in this list.

Blog posts

Contribution

Issues, bugs, and questions may be reported in the GitHub issue tracker for this project.

Pull requests are also welcome.

License

Copyright © 2016–present Mark Karpov

Distributed under BSD 3 clause license.