req
HTTP client library
Version on this page: | 3.13.1@rev:1 |
LTS Haskell 22.39: | 3.13.2@rev:4 |
Stackage Nightly 2024-10-31: | 3.13.4@rev:1 |
Latest on Hackage: | 3.13.4@rev:1 |
req-3.13.1@sha256:5776230dc4fccfff01d0c9109f7ecb1ec55241a214510ce3f5ad7f059186a623,3662
Module documentation for 3.13.1
- Network
- Network.HTTP
Req
{-# 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:
http-client
—low level HTTP client used everywhere in Haskell.http-client-tls
—TLS (HTTPS) support forhttp-client
.
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.
Related packages
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.
Changes
Req 3.13.1
-
Switched the non-pure test suite to use https://httpbun.org instead of https://httpbin.org since the latter proved to be highly unreliable lately.
-
Switched from
connection
tocrypton-connection
. -
Builds with GHC 9.6.1.
Req 3.13.0
- Add
headerRedacted
function to add header fields, which will be with redacted values on print.
Req 3.12.0
- Add
isStatusCodeException
function. - Add
instance HttpResponse (Network.HTTP.Client.Response ())
.
Req 3.11.0
- Add the
queryParamToList
method to theQueryParam
type class. - Add the
formToQuery
function. Issue 126. - Add
FromForm
instances (in theWeb.FormUrlEncoded
module) to theOption
andFormUrlEncodedParam
types.
Req 3.10.0
- Add
MonadHttp
instances fortransformers
types.
Req 3.9.2
- The test suite works with
aeson-2.x.x.x
.
Req 3.9.1
- Builds with GHC 9.0.
Req 3.9.0
- The
useHttpURI
anduseHttpsURI
functions now preserve trailing slashes.
Req 3.8.0
- Adjusted the value of the
httpConfigRetryJudgeException
field ofdefaultHttpConfig
to retry on response timeouts and connection timeouts.
Req 3.7.0
-
Added
reqCb
, a function that allows you to modify theRequest
object but otherwise performs the requst for you. -
Derived
MonadThrow
,MonadCatch
, andMonadMask
for theReq
monad.
Req 3.6.0
- Added the
httpConfigBodyPreviewLength
configuration parameter toHttpConfig
.
Req 3.5.0
- Made
Req
an instance ofMonadUnliftIO
. Issue 100.
Req 3.4.0
-
Requests using
DELETE
method can now have a body. Issue 89. -
Added the
httpConfigRetryJudgeException
field toHttpConfig
so that requests that result in exceptions can be retried. Issue 93. -
Added the function
renderUrl
. Issue 83.
Req 3.3.0
- Derived
Show
instances for response typesIgnoreResponse
,JsonResponse
,BsResponse
, andLbsResponse
.
Req 3.2.0
-
Made the tests pass with
http-client-0.7
and later. -
Added a quasiquoter for URL creation,
urlQ
.
Req 3.1.0
- Changed signature of
httpConfigRetryPolicy
toRetryPolicyM IO
.
Req 3.0.0
-
Dropped functions
parseUrlHttp
,parseUrlHttps
, andparseUrl
. Instead we now haveuseHttpURI
,useHttpsURI
, anduseURI
takeURI
s frommodern-uri
as their argument. You first parse your URL with themodern-uri
package and then pass it to those functions. This allows us to work with typed URI representations and seamlessly convert them to somethingreq
can work with. As a side effect basic auth from theURI
s is now taken into consideration. In the future we may also start to respect fragments ifhttp-client
starts to support this. -
Dropped support for GHC 8.2 and older.
Req 2.1.0
-
Dropped support for GHC 7.10.
-
Added the new
acceptHeader
method to theHttpResponse
type class. Notably, thejsonResponse
method now sets"Accept"
header to"application/json"
.
Req 2.0.1
- Fixed the
httpbin
tests (they changed something on the server again).
Req 2.0.0
- Got rid of
data-default-class
dependency, now we exportdefaultHttpConfig
instead.
Req 1.2.1
- Fixed a typo in the type signature of
parseUrl
.
Req 1.2.0
- Added the
parseUrl
function.
Req 1.1.0
-
Added
customAuth
andattachHeader
to facilitate creation of custom authentication options. -
Added
basicProxyAuth
authentication option.
Req 1.0.0
-
Added the
reqBr
function allowing to consumeResponse BodyReader
without using a pre-defined instance ofHttpResponse
, in a custom way. -
Now streaming of response body does not happen until we’ve checked headers and status code with
httpConfigCheckResponse
. It also doesn’t happen on every retry. Streaming and obtaining of final response value happens only once when we’re happy with everything.Previously we first tried to consume and interpret response body before checking status code and determining whether we should retry the request. This was not good, because we could expect a JSON response but get a response with status code 500, and then still we would try to parse it as JSON first before letting
httpConfigCheckResponse
throw an exception.The corrected behavior should also make retrying more efficient.
-
Changed signatures of several fields of
HttpConfig
:httpConfigCheckResponse
,httpConfigRetryPolicy
, andhttpConfigRetryJudge
in order to eliminate redundantIO
and prevent the possibility that these functions could start consumingBodyReader
. -
Removed the
makeResponsePreview
method from theHttpResponse
type class. Preview business is handled by the library automatically on a lower level now. Users do not need to concern themselves with such stuff. -
Changed the type signature of the
getHttpResponse
method of theHttpResponse
type class. Previously it left too much freedom (and responsibility) to implementers of the method. In fact, we now limit whatgetHttpResponse
does to just consuming and interpretingResponse BodyReader
, so we can properly control details of connection opening/closing etc., for the user. -
Dropped support for GHC 7.8.
-
Minor documentation improvements.
Req 0.5.0
-
Changed the signature of the
makeResponseBodyPreview
fromresponse -> IO ByteString
toresponse -> ByteString
. -
Minor documentation improvements.
Req 0.4.0
- Added the
Req
monad andrunReq
function to run it. This allows to usereq
without defining new (orphan) instances.
Req 0.3.1
- Added
basicAuthUnsafe
.
Req 0.3.0
-
Made URL parsing functions
parseUrlHttp
andparseUrlHttps
recognize port numbers. -
Added
req'
function that allows to perform requests via a callback that receives pre-constructed request and manager. -
Removed the
ReturnRequest
HTTP response implementation as it was not quite safe and was not going to work with retrying. Usereq'
instead for “pure” testing. -
Changed the type of
httpConfigCheckResponse
, so the second argument can be any instance ofHttpResponse
. -
Added built-in automatic retrying. See
httpConfigRetryPolicy
andhttpConfigRetryJudge
inHttpConfig
. The default configuration retries 5 times on request timeouts. -
Added the
makeResponseBodyPreview
method to theHttpResponse
type class that allows to specify how to build a “preview” of response body for inclusion into exceptions. -
Improved wording in the documentation and
README.md
.
Req 0.2.0
-
Added support for multipart form data in the form of
ReqBodyMultipart
body option andreqBodyMultipart
helper function. This also required a change in the type signature ofgetRequestContentType
, which now takesbody
, notProxy body
because we need to extract boundary frombody
and put it intoContent-Type
header. This change, however, shouldn’t be too dangerous for end-users. -
Added support for OAuth 1.0 authentication via
oAuth1
option.
Req 0.1.0
- Initial release.