Copyright | © 2016–present Mark Karpov |
---|---|
License | BSD 3 clause |
Maintainer | Mark Karpov <markkarpov92@gmail.com> |
Stability | experimental |
Portability | portable |
Safe Haskell | Safe-Inferred |
Language | GHC2021 |
The documentation below is structured in such a way that the most important information is presented first: you learn how to do HTTP requests, how to embed them in the monad you have, and then it gives you details about less-common things you may want to know about. The documentation is written with sufficient coverage of details and examples, and it's designed to be a complete tutorial on its own.
About the library
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.
Using with other libraries
- You won't need the low-level interface of
http-client
most of the time, but when you do, it's better to do a qualified import, becausehttp-client
has naming conflicts withreq
. - For streaming of large request bodies see the companion package
req-conduit
: https://hackage.haskell.org/package/req-conduit.
Lightweight, no risk solution
The library uses the following mature packages under the hood to guarantee you the best experience:
- https://hackage.haskell.org/package/http-client—low level HTTP client used everywhere in Haskell.
- https://hackage.haskell.org/package/http-client-tls—TLS (HTTPS)
support for
http-client
.
It's 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.
Synopsis
- req :: (MonadHttp m, HttpMethod method, HttpBody body, HttpResponse response, HttpBodyAllowed (AllowsBody method) (ProvidesBody body)) => method -> Url scheme -> body -> Proxy response -> Option scheme -> m response
- reqBr :: (MonadHttp m, HttpMethod method, HttpBody body, HttpBodyAllowed (AllowsBody method) (ProvidesBody body)) => method -> Url scheme -> body -> Option scheme -> (Response BodyReader -> IO a) -> m a
- reqCb :: (MonadHttp m, HttpMethod method, HttpBody body, HttpResponse response, HttpBodyAllowed (AllowsBody method) (ProvidesBody body)) => method -> Url scheme -> body -> Proxy response -> Option scheme -> (Request -> m Request) -> m response
- req' :: forall m method body scheme a. (MonadHttp m, HttpMethod method, HttpBody body, HttpBodyAllowed (AllowsBody method) (ProvidesBody body)) => method -> Url scheme -> body -> Option scheme -> (Request -> Manager -> m a) -> m a
- withReqManager :: MonadIO m => (Manager -> m a) -> m a
- class MonadIO m => MonadHttp m where
- handleHttpException :: HttpException -> m a
- getHttpConfig :: m HttpConfig
- data HttpConfig = HttpConfig {
- httpConfigProxy :: Maybe Proxy
- httpConfigRedirectCount :: Int
- httpConfigAltManager :: Maybe Manager
- httpConfigCheckResponse :: forall b. Request -> Response b -> ByteString -> Maybe HttpExceptionContent
- httpConfigRetryPolicy :: RetryPolicyM IO
- httpConfigRetryJudge :: forall b. RetryStatus -> Response b -> Bool
- httpConfigRetryJudgeException :: RetryStatus -> SomeException -> Bool
- httpConfigBodyPreviewLength :: forall a. Num a => a
- defaultHttpConfig :: HttpConfig
- data Req a
- runReq :: MonadIO m => HttpConfig -> Req a -> m a
- data GET = GET
- data POST = POST
- data HEAD = HEAD
- data PUT = PUT
- data DELETE = DELETE
- data TRACE = TRACE
- data CONNECT = CONNECT
- data OPTIONS = OPTIONS
- data PATCH = PATCH
- class HttpMethod a where
- type AllowsBody a :: CanHaveBody
- httpMethodName :: Proxy a -> ByteString
- data Url (scheme :: Scheme)
- http :: Text -> Url 'Http
- https :: Text -> Url 'Https
- (/~) :: ToHttpApiData a => Url scheme -> a -> Url scheme
- (/:) :: Url scheme -> Text -> Url scheme
- useHttpURI :: URI -> Maybe (Url 'Http, Option scheme)
- useHttpsURI :: URI -> Maybe (Url 'Https, Option scheme)
- useURI :: URI -> Maybe (Either (Url 'Http, Option scheme0) (Url 'Https, Option scheme1))
- urlQ :: QuasiQuoter
- renderUrl :: Url scheme -> Text
- data NoReqBody = NoReqBody
- newtype ReqBodyJson a = ReqBodyJson a
- newtype ReqBodyFile = ReqBodyFile FilePath
- newtype ReqBodyBs = ReqBodyBs ByteString
- newtype ReqBodyLbs = ReqBodyLbs ByteString
- newtype ReqBodyUrlEnc = ReqBodyUrlEnc FormUrlEncodedParam
- data FormUrlEncodedParam
- data ReqBodyMultipart
- reqBodyMultipart :: MonadIO m => [Part] -> m ReqBodyMultipart
- class HttpBody body where
- getRequestBody :: body -> RequestBody
- getRequestContentType :: body -> Maybe ByteString
- type family ProvidesBody body :: CanHaveBody where ...
- type family HttpBodyAllowed (allowsBody :: CanHaveBody) (providesBody :: CanHaveBody) :: Constraint where ...
- data Option (scheme :: Scheme)
- (=:) :: (QueryParam param, ToHttpApiData a) => Text -> a -> param
- queryFlag :: QueryParam param => Text -> param
- formToQuery :: (QueryParam param, Monoid param, ToForm f) => f -> param
- class QueryParam param where
- queryParam :: ToHttpApiData a => Text -> Maybe a -> param
- queryParamToList :: param -> [(Text, Maybe Text)]
- header :: ByteString -> ByteString -> Option scheme
- attachHeader :: ByteString -> ByteString -> Request -> Request
- headerRedacted :: ByteString -> ByteString -> Option scheme
- cookieJar :: CookieJar -> Option scheme
- basicAuth :: ByteString -> ByteString -> Option 'Https
- basicAuthUnsafe :: ByteString -> ByteString -> Option scheme
- basicProxyAuth :: ByteString -> ByteString -> Option scheme
- oAuth1 :: ByteString -> ByteString -> ByteString -> ByteString -> Option scheme
- oAuth2Bearer :: ByteString -> Option 'Https
- oAuth2Token :: ByteString -> Option 'Https
- customAuth :: (Request -> IO Request) -> Option scheme
- port :: Int -> Option scheme
- decompress :: (ByteString -> Bool) -> Option scheme
- responseTimeout :: Int -> Option scheme
- httpVersion :: Int -> Int -> Option scheme
- data IgnoreResponse
- ignoreResponse :: Proxy IgnoreResponse
- data JsonResponse a
- jsonResponse :: Proxy (JsonResponse a)
- data BsResponse
- bsResponse :: Proxy BsResponse
- data LbsResponse
- lbsResponse :: Proxy LbsResponse
- responseBody :: HttpResponse response => response -> HttpResponseBody response
- responseStatusCode :: HttpResponse response => response -> Int
- responseStatusMessage :: HttpResponse response => response -> ByteString
- responseHeader :: HttpResponse response => response -> ByteString -> Maybe ByteString
- responseCookieJar :: HttpResponse response => response -> CookieJar
- class HttpResponse response where
- type HttpResponseBody response :: Type
- toVanillaResponse :: response -> Response (HttpResponseBody response)
- getHttpResponse :: Response BodyReader -> IO response
- acceptHeader :: Proxy response -> Maybe ByteString
- data HttpException
- isStatusCodeException :: HttpException -> Maybe (Response ())
- data CanHaveBody
- data Scheme
Making a request
To make an HTTP request you normally need only one function: req
.
:: (MonadHttp m, HttpMethod method, HttpBody body, HttpResponse response, HttpBodyAllowed (AllowsBody method) (ProvidesBody body)) | |
=> method | HTTP method |
-> Url scheme |
|
-> body | Body of the request |
-> Proxy response | A hint how to interpret response |
-> Option scheme | Collection of optional parameters |
-> m response | Response |
Make an HTTP request. The function takes 5 arguments, 4 of which
specify required parameters and the final Option
argument is a
collection of optional parameters.
Let's go through all the arguments first: req method url body response
options
.
method
is an HTTP method such as GET
or POST
. The documentation has
a dedicated section about HTTP methods below.
url
is a Url
that describes location of resource you want to interact
with.
body
is a body option such as NoReqBody
or ReqBodyJson
. The
tutorial has a section about HTTP bodies, but usage is very
straightforward and should be clear from the examples.
response
is a type hint how to make and interpret response of an HTTP
request. Out-of-the-box it can be the following:
ignoreResponse
jsonResponse
bsResponse
(to get a strictByteString
)lbsResponse
(to get a lazyByteString
)
Finally, options
is a Monoid
that holds a composite Option
for all
other optional settings like query parameters, headers, non-standard port
number, etc. There are quite a few things you can put there, see the
corresponding section in the documentation. If you don't need anything at
all, pass mempty
.
Note that if you use req
to do all your requests, connection
sharing and reuse is done for you automatically.
See the examples below to get on the speed quickly.
Examples
First, this is a piece of boilerplate that should be in place before you try the examples:
{-# LANGUAGE DeriveGeneric #-} {-# LANGUAGE OverloadedStrings #-} module Main (main) where import Control.Monad import Control.Monad.IO.Class import Data.Aeson import Data.Maybe (fromJust) import Data.Monoid ((<>)) import Data.Text (Text) import GHC.Generics import Network.HTTP.Req import qualified Data.ByteString.Char8 as B import qualified Text.URI as URI
We will be making requests against the https://httpbin.org service.
Make a GET request, grab 5 random bytes:
main :: IO () main = runReq defaultHttpConfig $ do let n :: Int n = 5 bs <- req GET (https "httpbin.org" /: "bytes" /~ n) NoReqBody bsResponse mempty liftIO $ B.putStrLn (responseBody bs)
The same, but now we use a query parameter named "seed"
to control
seed of the generator:
main :: IO () main = runReq defaultHttpConfig $ do let n, seed :: Int n = 5 seed = 100 bs <- req GET (https "httpbin.org" /: "bytes" /~ n) NoReqBody bsResponse $ "seed" =: seed liftIO $ B.putStrLn (responseBody bs)
POST JSON data and get some info about the POST request:
data MyData = MyData { size :: Int , color :: Text } deriving (Show, Generic) instance ToJSON MyData instance FromJSON MyData main :: IO () main = runReq defaultHttpConfig $ do let myData = MyData { size = 6 , color = "Green" } v <- req POST (https "httpbin.org" /: "post") (ReqBodyJson myData) jsonResponse mempty liftIO $ print (responseBody v :: Value)
Sending URL-encoded body:
main :: IO () main = runReq defaultHttpConfig $ do let params = "foo" =: ("bar" :: Text) <> queryFlag "baz" response <- req POST (https "httpbin.org" /: "post") (ReqBodyUrlEnc params) jsonResponse mempty liftIO $ print (responseBody response :: Value)
Using various optional parameters and URL that is not known in advance:
main :: IO () main = runReq defaultHttpConfig $ do -- This is an example of what to do when URL is given dynamically. Of -- course in a real application you may not want to use 'fromJust'. uri <- URI.mkURI "https://httpbin.org/get?foo=bar" let (url, options) = fromJust (useHttpsURI uri) response <- req GET url NoReqBody jsonResponse $ "from" =: (15 :: Int) <> "to" =: (67 :: Int) <> basicAuth "username" "password" <> options <> -- contains the ?foo=bar part port 443 -- here you can put any port of course liftIO $ print (responseBody response :: Value)
:: (MonadHttp m, HttpMethod method, HttpBody body, HttpBodyAllowed (AllowsBody method) (ProvidesBody body)) | |
=> method | HTTP method |
-> Url scheme |
|
-> body | Body of the request |
-> Option scheme | Collection of optional parameters |
-> (Response BodyReader -> IO a) | How to consume response |
-> m a | Result |
A version of req
that does not use one of the predefined instances of
HttpResponse
but instead allows the user to consume
manually, in a custom way.Response
BodyReader
Since: 1.0.0
:: (MonadHttp m, HttpMethod method, HttpBody body, HttpResponse response, HttpBodyAllowed (AllowsBody method) (ProvidesBody body)) | |
=> method | HTTP method |
-> Url scheme |
|
-> body | Body of the request |
-> Proxy response | A hint how to interpret response |
-> Option scheme | Collection of optional parameters |
-> (Request -> m Request) | Callback to modify the request |
-> m response | Response |
:: forall m method body scheme a. (MonadHttp m, HttpMethod method, HttpBody body, HttpBodyAllowed (AllowsBody method) (ProvidesBody body)) | |
=> method | HTTP method |
-> Url scheme |
|
-> body | Body of the request |
-> Option scheme | Collection of optional parameters |
-> (Request -> Manager -> m a) | How to perform request |
-> m a | Result |
Mostly like req
with respect to its arguments, but accepts a callback
that allows to perform a request in arbitrary fashion.
This function does not perform handling/wrapping exceptions, checking
response (with httpConfigCheckResponse
), and retrying. It only prepares
Request
and allows you to use it.
Since: 0.3.0
withReqManager :: MonadIO m => (Manager -> m a) -> m a Source #
Embedding requests in your monad
To use req
in your monad, all you need to do is to make the monad an
instance of the MonadHttp
type class.
When writing a library, keep your API polymorphic in terms of
MonadHttp
, only define instance of MonadHttp
in final application.
Another option is to use a newtype
-wrapped monad stack and define
MonadHttp
for it. As of the version 0.4.0, the Req
monad that
follows this strategy is provided out-of-the-box (see below).
class MonadIO m => MonadHttp m where Source #
A type class for monads that support performing HTTP requests.
Typically, you only need to define the handleHttpException
method
unless you want to tweak HttpConfig
.
handleHttpException :: HttpException -> m a Source #
This method describes how to deal with HttpException
that was
caught by the library. One option is to re-throw it if you are OK with
exceptions, but if you prefer working with something like
MonadError
, this is the right place to pass it to
throwError
.
getHttpConfig :: m HttpConfig Source #
Return the HttpConfig
to be used when performing HTTP requests.
Default implementation returns its def
value, which is described in
the documentation for the type. Common usage pattern with manually
defined getHttpConfig
is to return some hard-coded value, or a value
extracted from MonadReader
if a more flexible
approach to configuration is desirable.
Instances
data HttpConfig Source #
HttpConfig
contains settings to be used when making HTTP requests.
HttpConfig | |
|
defaultHttpConfig :: HttpConfig Source #
The default value of HttpConfig
.
Since: 2.0.0
A monad that allows us to run req
in any IO
-enabled monad without
having to define new instances.
Since: 0.4.0
Instances
MonadIO Req Source # | |
Defined in Network.HTTP.Req | |
Applicative Req Source # | |
Functor Req Source # | |
Monad Req Source # | |
MonadCatch Req Source # | Since: 3.7.0 |
Defined in Network.HTTP.Req | |
MonadMask Req Source # | Since: 3.7.0 |
Defined in Network.HTTP.Req mask :: HasCallStack => ((forall a. Req a -> Req a) -> Req b) -> Req b # uninterruptibleMask :: HasCallStack => ((forall a. Req a -> Req a) -> Req b) -> Req b # generalBracket :: HasCallStack => Req a -> (a -> ExitCase b -> Req c) -> (a -> Req b) -> Req (b, c) # | |
MonadThrow Req Source # | Since: 3.7.0 |
Defined in Network.HTTP.Req throwM :: (HasCallStack, Exception e) => e -> Req a # | |
MonadHttp Req Source # | |
Defined in Network.HTTP.Req handleHttpException :: HttpException -> Req a Source # | |
MonadUnliftIO Req Source # | |
Defined in Network.HTTP.Req | |
MonadBaseControl IO Req Source # | |
MonadBase IO Req Source # | |
Defined in Network.HTTP.Req | |
type StM Req a Source # | |
Defined in Network.HTTP.Req |
:: MonadIO m | |
=> HttpConfig |
|
-> Req a | Computation to run |
-> m a |
Run a computation in the Req
monad with the given HttpConfig
. In
the case of an exceptional situation an HttpException
will be thrown.
Since: 0.4.0
Request
Method
The package supports all methods as defined by RFC 2616, and PATCH
which is defined by RFC 5789—that should be enough to talk to RESTful
APIs. In some cases, however, you may want to add more methods (e.g. you
work with WebDAV https://en.wikipedia.org/wiki/WebDAV); no need to
compromise on type safety and hack, it only takes a couple of seconds to
define a new method that will works seamlessly, see HttpMethod
.
GET
method.
Instances
HttpMethod GET Source # | |
Defined in Network.HTTP.Req type AllowsBody GET :: CanHaveBody Source # httpMethodName :: Proxy GET -> ByteString Source # | |
type AllowsBody GET Source # | |
Defined in Network.HTTP.Req |
POST
method.
Instances
HttpMethod POST Source # | |
Defined in Network.HTTP.Req type AllowsBody POST :: CanHaveBody Source # httpMethodName :: Proxy POST -> ByteString Source # | |
type AllowsBody POST Source # | |
Defined in Network.HTTP.Req |
HEAD
method.
Instances
HttpMethod HEAD Source # | |
Defined in Network.HTTP.Req type AllowsBody HEAD :: CanHaveBody Source # httpMethodName :: Proxy HEAD -> ByteString Source # | |
type AllowsBody HEAD Source # | |
Defined in Network.HTTP.Req |
PUT
method.
Instances
HttpMethod PUT Source # | |
Defined in Network.HTTP.Req type AllowsBody PUT :: CanHaveBody Source # httpMethodName :: Proxy PUT -> ByteString Source # | |
type AllowsBody PUT Source # | |
Defined in Network.HTTP.Req |
DELETE
method. RFC 7231 allows a payload in DELETE but without
semantics.
Note: before version 3.4.0 this method did not allow request bodies.
Instances
HttpMethod DELETE Source # | |
Defined in Network.HTTP.Req type AllowsBody DELETE :: CanHaveBody Source # httpMethodName :: Proxy DELETE -> ByteString Source # | |
type AllowsBody DELETE Source # | |
Defined in Network.HTTP.Req |
TRACE
method.
Instances
HttpMethod TRACE Source # | |
Defined in Network.HTTP.Req type AllowsBody TRACE :: CanHaveBody Source # httpMethodName :: Proxy TRACE -> ByteString Source # | |
type AllowsBody TRACE Source # | |
Defined in Network.HTTP.Req |
CONNECT
method.
Instances
HttpMethod CONNECT Source # | |
Defined in Network.HTTP.Req type AllowsBody CONNECT :: CanHaveBody Source # httpMethodName :: Proxy CONNECT -> ByteString Source # | |
type AllowsBody CONNECT Source # | |
Defined in Network.HTTP.Req |
OPTIONS
method.
Instances
HttpMethod OPTIONS Source # | |
Defined in Network.HTTP.Req type AllowsBody OPTIONS :: CanHaveBody Source # httpMethodName :: Proxy OPTIONS -> ByteString Source # | |
type AllowsBody OPTIONS Source # | |
Defined in Network.HTTP.Req |
PATCH
method.
Instances
HttpMethod PATCH Source # | |
Defined in Network.HTTP.Req type AllowsBody PATCH :: CanHaveBody Source # httpMethodName :: Proxy PATCH -> ByteString Source # | |
type AllowsBody PATCH Source # | |
Defined in Network.HTTP.Req |
class HttpMethod a where Source #
A type class for types that can be used as an HTTP method. To define a
non-standard method, follow this example that defines COPY
:
data COPY = COPY instance HttpMethod COPY where type AllowsBody COPY = 'CanHaveBody httpMethodName Proxy = "COPY"
type AllowsBody a :: CanHaveBody Source #
Type function AllowsBody
returns a type of kind CanHaveBody
which
tells the rest of the library whether the method can have body or not.
We use the special type CanHaveBody
lifted to the kind level instead
of Bool
to get more user-friendly compiler messages.
httpMethodName :: Proxy a -> ByteString Source #
Return name of the method as a ByteString
.
Instances
URL
We use Url
s which are correct by construction, see Url
. To build a
Url
from a URI
, use useHttpURI
, useHttpsURI
, or generic useURI
.
data Url (scheme :: Scheme) Source #
Request's Url
. Start constructing your Url
with http
or https
specifying the scheme and host at the same time. Then use the (
and /~
)(
operators to grow the path one piece at a time. Every single
piece of path will be url(percent)-encoded, so using /:
)(
and
/~
)(
is the only way to have forward slashes between path segments.
This approach makes working with dynamic path segments easy and safe. See
examples below how to represent various /:
)Url
s (make sure the
OverloadedStrings
language extension is enabled).
Examples
http "httpbin.org" -- http://httpbin.org
https "httpbin.org" -- https://httpbin.org
https "httpbin.org" /: "encoding" /: "utf8" -- https://httpbin.org/encoding/utf8
https "httpbin.org" /: "foo" /: "bar/baz" -- https://httpbin.org/foo/bar%2Fbaz
https "httpbin.org" /: "bytes" /~ (10 :: Int) -- https://httpbin.org/bytes/10
https "юникод.рф" -- https://%D1%8E%D0%BD%D0%B8%D0%BA%D0%BE%D0%B4.%D1%80%D1%84
Instances
Typeable scheme => Lift (Url scheme :: Type) Source # | |
Typeable scheme => Data (Url scheme) Source # | |
Defined in Network.HTTP.Req gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> Url scheme -> c (Url scheme) # gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c (Url scheme) # toConstr :: Url scheme -> Constr # dataTypeOf :: Url scheme -> DataType # dataCast1 :: Typeable t => (forall d. Data d => c (t d)) -> Maybe (c (Url scheme)) # dataCast2 :: Typeable t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c (Url scheme)) # gmapT :: (forall b. Data b => b -> b) -> Url scheme -> Url scheme # gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> Url scheme -> r # gmapQr :: forall r r'. (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> Url scheme -> r # gmapQ :: (forall d. Data d => d -> u) -> Url scheme -> [u] # gmapQi :: Int -> (forall d. Data d => d -> u) -> Url scheme -> u # gmapM :: Monad m => (forall d. Data d => d -> m d) -> Url scheme -> m (Url scheme) # gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> Url scheme -> m (Url scheme) # gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> Url scheme -> m (Url scheme) # | |
Generic (Url scheme) Source # | |
Show (Url scheme) Source # | |
Eq (Url scheme) Source # | |
Ord (Url scheme) Source # | |
type Rep (Url scheme) Source # | |
Defined in Network.HTTP.Req type Rep (Url scheme) = D1 ('MetaData "Url" "Network.HTTP.Req" "req-3.13.3-HNskJKOXnhK1SbK2hnOo99" 'False) (C1 ('MetaCons "Url" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Scheme) :*: S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (NonEmpty Text)))) |
http :: Text -> Url 'Http Source #
Given host name, produce a Url
which has “http” as its scheme and
empty path. This also sets port to 80
.
https :: Text -> Url 'Https Source #
Given host name, produce a Url
which has “https” as its scheme and
empty path. This also sets port to 443
.
(/~) :: ToHttpApiData a => Url scheme -> a -> Url scheme infixl 5 Source #
Grow a given Url
appending a single path segment to it. Note that the
path segment can be of any type that is an instance of ToHttpApiData
.
useHttpURI :: URI -> Maybe (Url 'Http, Option scheme) Source #
The useHttpURI
function provides an alternative method to get Url
(possibly with some Option
s) from a URI
. This is useful when you are
given a URL to query dynamically and don't know it beforehand.
This function expects the scheme to be “http” and host to be present.
Since: 3.0.0
useHttpsURI :: URI -> Maybe (Url 'Https, Option scheme) Source #
Just like useHttpURI
, but expects the “https” scheme.
Since: 3.0.0
useURI :: URI -> Maybe (Either (Url 'Http, Option scheme0) (Url 'Https, Option scheme1)) Source #
A combination of useHttpURI
and useHttpsURI
for cases when scheme
is not known in advance.
Since: 3.0.0
urlQ :: QuasiQuoter Source #
Body
A number of options for request bodies are available. The Content-Type
header is set for you automatically according to the body option you use
(it's always specified in the documentation for a given body option). To
add your own way to represent request body, define an instance of
HttpBody
.
This data type represents empty body of an HTTP request. This is the
data type to use with HttpMethod
s that cannot have a body, as it's the
only type for which ProvidesBody
returns NoBody
.
Using of this body option does not set the Content-Type
header.
Instances
HttpBody NoReqBody Source # | |
Defined in Network.HTTP.Req |
newtype ReqBodyJson a Source #
This body option allows us to use a JSON object as the request
body—probably the most popular format right now. Just wrap a data type
that is an instance of ToJSON
type class and you are done: it will be
converted to JSON and inserted as request body.
This body option sets the Content-Type
header to "application/json;
charset=utf-8"
value.
Instances
ToJSON a => HttpBody (ReqBodyJson a) Source # | |
Defined in Network.HTTP.Req getRequestBody :: ReqBodyJson a -> RequestBody Source # getRequestContentType :: ReqBodyJson a -> Maybe ByteString Source # |
newtype ReqBodyFile Source #
This body option streams request body from a file. It is expected that the file size does not change during streaming.
Using of this body option does not set the Content-Type
header.
Instances
HttpBody ReqBodyFile Source # | |
Defined in Network.HTTP.Req |
HTTP request body represented by a strict ByteString
.
Using of this body option does not set the Content-Type
header.
Instances
HttpBody ReqBodyBs Source # | |
Defined in Network.HTTP.Req |
newtype ReqBodyLbs Source #
HTTP request body represented by a lazy ByteString
.
Using of this body option does not set the Content-Type
header.
Instances
HttpBody ReqBodyLbs Source # | |
Defined in Network.HTTP.Req |
newtype ReqBodyUrlEnc Source #
URL-encoded body. This can hold a collection of parameters which are
encoded similarly to query parameters at the end of query string, with
the only difference that they are stored in request body. The similarity
is reflected in the API as well, as you can use the same combinators you
would use to add query parameters: (
and =:
)queryFlag
.
This body option sets the Content-Type
header to
"application/x-www-form-urlencoded"
value.
Instances
HttpBody ReqBodyUrlEnc Source # | |
Defined in Network.HTTP.Req |
data FormUrlEncodedParam Source #
An opaque monoidal value that allows to collect URL-encoded parameters
to be wrapped in ReqBodyUrlEnc
.
Instances
Monoid FormUrlEncodedParam Source # | |
Defined in Network.HTTP.Req | |
Semigroup FormUrlEncodedParam Source # | |
Defined in Network.HTTP.Req (<>) :: FormUrlEncodedParam -> FormUrlEncodedParam -> FormUrlEncodedParam # sconcat :: NonEmpty FormUrlEncodedParam -> FormUrlEncodedParam # stimes :: Integral b => b -> FormUrlEncodedParam -> FormUrlEncodedParam # | |
FromForm FormUrlEncodedParam Source # | Use Since: 3.11.0 |
Defined in Network.HTTP.Req | |
QueryParam FormUrlEncodedParam Source # | |
Defined in Network.HTTP.Req queryParam :: ToHttpApiData a => Text -> Maybe a -> FormUrlEncodedParam Source # queryParamToList :: FormUrlEncodedParam -> [(Text, Maybe Text)] Source # |
data ReqBodyMultipart Source #
Multipart form data. Please consult the
Network.HTTP.Client.MultipartFormData module for how to construct
parts, then use reqBodyMultipart
to create actual request body from the
parts. reqBodyMultipart
is the only way to get a value of the type
ReqBodyMultipart
, as its constructor is not exported on purpose.
Examples
import Control.Monad.IO.Class import Data.Default.Class import Network.HTTP.Req import qualified Network.HTTP.Client.MultipartFormData as LM main :: IO () main = runReq def $ do body <- reqBodyMultipart [ LM.partBS "title" "My Image" , LM.partFileSource "file1" "/tmp/image.jpg" ] response <- req POST (http "example.com" /: "post") body bsResponse mempty liftIO $ print (responseBody response)
Since: 0.2.0
Instances
reqBodyMultipart :: MonadIO m => [Part] -> m ReqBodyMultipart Source #
Create ReqBodyMultipart
request body from a collection of Part
s.
Since: 0.2.0
class HttpBody body where Source #
A type class for things that can be interpreted as an HTTP
RequestBody
.
getRequestBody :: body -> RequestBody Source #
How to get actual RequestBody
.
getRequestContentType :: body -> Maybe ByteString Source #
This method allows us to optionally specify the value of
Content-Type
header that should be used with particular body option.
By default it returns Nothing
and so Content-Type
is not set.
Instances
HttpBody NoReqBody Source # | |
Defined in Network.HTTP.Req | |
HttpBody ReqBodyBs Source # | |
Defined in Network.HTTP.Req | |
HttpBody ReqBodyFile Source # | |
Defined in Network.HTTP.Req | |
HttpBody ReqBodyLbs Source # | |
Defined in Network.HTTP.Req | |
HttpBody ReqBodyMultipart Source # | |
Defined in Network.HTTP.Req | |
HttpBody ReqBodyUrlEnc Source # | |
Defined in Network.HTTP.Req | |
ToJSON a => HttpBody (ReqBodyJson a) Source # | |
Defined in Network.HTTP.Req getRequestBody :: ReqBodyJson a -> RequestBody Source # getRequestContentType :: ReqBodyJson a -> Maybe ByteString Source # |
type family ProvidesBody body :: CanHaveBody where ... Source #
The type function recognizes NoReqBody
as having NoBody
, while any
other body option CanHaveBody
. This forces the user to use NoReqBody
with GET
method and other methods that should not have body.
ProvidesBody NoReqBody = 'NoBody | |
ProvidesBody body = 'CanHaveBody |
type family HttpBodyAllowed (allowsBody :: CanHaveBody) (providesBody :: CanHaveBody) :: Constraint where ... Source #
This type function allows any HTTP body if method says it
CanHaveBody
. When the method says it should have NoBody
, the only
body option to use is NoReqBody
.
HttpBodyAllowed 'NoBody 'NoBody = () | |
HttpBodyAllowed 'CanHaveBody body = () | |
HttpBodyAllowed 'NoBody 'CanHaveBody = TypeError ('Text "This HTTP method does not allow attaching a request body.") |
Optional parameters
Optional parameters of request include things like query parameters,
headers, port number, etc. All optional parameters have the type
Option
, which is a Monoid
. This means that you can use mempty
as
the last argument of req
to specify no optional parameters, or combine
Option
s using mappend
or (
to have several of them at once.<>
)
data Option (scheme :: Scheme) Source #
The opaque Option
type is a Monoid
you can use to pack collection
of optional parameters like query parameters and headers. See sections
below to learn which Option
primitives are available.
Instances
Monoid (Option scheme) Source # | |
Semigroup (Option scheme) Source # | |
FromForm (Option scheme) Source # | Use Since: 3.11.0 |
QueryParam (Option scheme) Source # | |
Defined in Network.HTTP.Req queryParam :: ToHttpApiData a => Text -> Maybe a -> Option scheme Source # queryParamToList :: Option scheme -> [(Text, Maybe Text)] Source # |
Query parameters
This section describes a polymorphic interface that can be used to
construct query parameters (of the type Option
) and form URL-encoded
bodies (of the type FormUrlEncodedParam
).
(=:) :: (QueryParam param, ToHttpApiData a) => Text -> a -> param infix 7 Source #
This operator builds a query parameter that will be included in URL of
your request after the question sign ?
. This is the same syntax you use
with form URL encoded request bodies.
This operator is defined in terms of queryParam
:
name =: value = queryParam name (pure value)
queryFlag :: QueryParam param => Text -> param Source #
Construct a flag, that is, a valueless query parameter. For example, in
the following URL "a"
is a flag, while "b"
is a query parameter
with a value:
https://httpbin.org/foo/bar?a&b=10
This operator is defined in terms of queryParam
:
queryFlag name = queryParam name (Nothing :: Maybe ())
formToQuery :: (QueryParam param, Monoid param, ToForm f) => f -> param Source #
Construct query parameters from a ToForm
instance. This function
produces the same query params as urlEncodeAsFormStable
.
Note that Form
doesn't have the concept of parameters with the
empty value (i.e. what you can get by key =: ""
). If the value is
empty, it will be encoded as a valueless parameter (i.e. what you can get
by queryFlag key
).
Since: 3.11.0
class QueryParam param where Source #
A type class for query-parameter-like things. The reason to have an
overloaded queryParam
is to be able to use it as an Option
and as a
FormUrlEncodedParam
when constructing form URL encoded request bodies.
Having the same syntax for these cases seems natural and user-friendly.
queryParam :: ToHttpApiData a => Text -> Maybe a -> param Source #
Create a query parameter with given name and value. If value is
Nothing
, it won't be included at all (i.e. you create a flag this
way). It's recommended to use (
and =:
)queryFlag
instead of this
method, because they are easier to read.
queryParamToList :: param -> [(Text, Maybe Text)] Source #
Get the query parameter names and values set by queryParam
.
Since: 3.11.0
Instances
QueryParam FormUrlEncodedParam Source # | |
Defined in Network.HTTP.Req queryParam :: ToHttpApiData a => Text -> Maybe a -> FormUrlEncodedParam Source # queryParamToList :: FormUrlEncodedParam -> [(Text, Maybe Text)] Source # | |
QueryParam (Option scheme) Source # | |
Defined in Network.HTTP.Req queryParam :: ToHttpApiData a => Text -> Maybe a -> Option scheme Source # queryParamToList :: Option scheme -> [(Text, Maybe Text)] Source # |
Headers
:: ByteString | Header name |
-> ByteString | Header value |
-> Option scheme |
attachHeader :: ByteString -> ByteString -> Request -> Request Source #
Attach a header with given name and content to a Request
.
Since: 1.1.0
headerRedacted :: ByteString -> ByteString -> Option scheme Source #
Same as header
, but with redacted values on print.
Since: 3.13.0
Cookies
Support for cookies is quite minimalistic at the moment. It's possible to
specify which cookies to send using cookieJar
and inspect Response
to extract CookieJar
from it (see responseCookieJar
).
Authentication
This section provides the common authentication helpers in the form of
Option
s. You should always prefer the provided authentication Option
s
to manual construction of headers because it ensures that you only use
one authentication method at a time (they overwrite each other) and
provides additional type safety that prevents leaking of credentials in
the cases when authentication relies on HTTPS for encrypting sensitive
data.
:: ByteString | Username |
-> ByteString | Password |
-> Option 'Https | Auth |
The Option
adds basic authentication.
See also: https://en.wikipedia.org/wiki/Basic_access_authentication.
:: ByteString | Username |
-> ByteString | Password |
-> Option scheme | Auth |
:: ByteString | Username |
-> ByteString | Password |
-> Option scheme | Auth |
The Option
set basic proxy authentication header.
Since: 1.1.0
:: ByteString | Consumer token |
-> ByteString | Consumer secret |
-> ByteString | OAuth token |
-> ByteString | OAuth token secret |
-> Option scheme | Auth |
The Option
adds OAuth1 authentication.
Since: 0.2.0
:: ByteString | Token |
-> Option 'Https | Auth |
The Option
adds an OAuth2 bearer token. This is treated by many
services as the equivalent of a username and password.
The Option
is defined as:
oAuth2Bearer token = header "Authorization" ("Bearer " <> token)
See also: https://en.wikipedia.org/wiki/OAuth.
:: ByteString | Token |
-> Option 'Https | Auth |
The Option
adds a not-quite-standard OAuth2 bearer token (that seems
to be used only by GitHub). This will be treated by whatever services
accept it as the equivalent of a username and password.
The Option
is defined as:
oAuth2Token token = header "Authorization" ("token" <> token)
See also: https://developer.github.com/v3/oauth#3-use-the-access-token-to-access-the-api.
Other
:: (ByteString -> Bool) | Predicate that is given MIME type, it returns |
-> Option scheme |
This Option
controls whether gzipped data should be decompressed on
the fly. By default everything except for "application/x-tar"
is
decompressed, i.e. we have:
decompress (/= "application/x-tar")
You can also choose to decompress everything like this:
decompress (const True)
Specify the number of microseconds to wait for response. The default
value is 30 seconds (defined in ManagerSettings
of connection
Manager
).
HTTP version to send to the server, the default is HTTP 1.1.
Response
Response interpretations
data IgnoreResponse Source #
Make a request and ignore the body of the response.
Instances
Show IgnoreResponse Source # | |
Defined in Network.HTTP.Req showsPrec :: Int -> IgnoreResponse -> ShowS # show :: IgnoreResponse -> String # showList :: [IgnoreResponse] -> ShowS # | |
HttpResponse IgnoreResponse Source # | |
type HttpResponseBody IgnoreResponse Source # | |
Defined in Network.HTTP.Req |
ignoreResponse :: Proxy IgnoreResponse Source #
Use this as the fourth argument of req
to specify that you want it to
ignore the response body.
data JsonResponse a Source #
Make a request and interpret the body of the response as JSON. The
handleHttpException
method of MonadHttp
instance corresponding to
monad in which you use req
will determine what to do in the case when
parsing fails (the JsonHttpException
constructor will be used).
Instances
Show a => Show (JsonResponse a) Source # | |
Defined in Network.HTTP.Req showsPrec :: Int -> JsonResponse a -> ShowS # show :: JsonResponse a -> String # showList :: [JsonResponse a] -> ShowS # | |
FromJSON a => HttpResponse (JsonResponse a) Source # | |
Defined in Network.HTTP.Req type HttpResponseBody (JsonResponse a) Source # toVanillaResponse :: JsonResponse a -> Response (HttpResponseBody (JsonResponse a)) Source # getHttpResponse :: Response BodyReader -> IO (JsonResponse a) Source # acceptHeader :: Proxy (JsonResponse a) -> Maybe ByteString Source # | |
type HttpResponseBody (JsonResponse a) Source # | |
Defined in Network.HTTP.Req |
jsonResponse :: Proxy (JsonResponse a) Source #
Use this as the fourth argument of req
to specify that you want it to
return the JsonResponse
interpretation.
data BsResponse Source #
Make a request and interpret the body of the response as a strict
ByteString
.
Instances
Show BsResponse Source # | |
Defined in Network.HTTP.Req showsPrec :: Int -> BsResponse -> ShowS # show :: BsResponse -> String # showList :: [BsResponse] -> ShowS # | |
HttpResponse BsResponse Source # | |
Defined in Network.HTTP.Req | |
type HttpResponseBody BsResponse Source # | |
Defined in Network.HTTP.Req |
bsResponse :: Proxy BsResponse Source #
Use this as the fourth argument of req
to specify that you want to
interpret the response body as a strict ByteString
.
data LbsResponse Source #
Make a request and interpret the body of the response as a lazy
ByteString
.
Instances
Show LbsResponse Source # | |
Defined in Network.HTTP.Req showsPrec :: Int -> LbsResponse -> ShowS # show :: LbsResponse -> String # showList :: [LbsResponse] -> ShowS # | |
HttpResponse LbsResponse Source # | |
Defined in Network.HTTP.Req | |
type HttpResponseBody LbsResponse Source # | |
Defined in Network.HTTP.Req |
lbsResponse :: Proxy LbsResponse Source #
Use this as the fourth argument of req
to specify that you want to
interpret the response body as a lazy ByteString
.
Inspecting a response
responseBody :: HttpResponse response => response -> HttpResponseBody response Source #
Get the response body.
responseStatusCode :: HttpResponse response => response -> Int Source #
Get the response status code.
responseStatusMessage :: HttpResponse response => response -> ByteString Source #
Get the response status message.
:: HttpResponse response | |
=> response | Response interpretation |
-> ByteString | Header to lookup |
-> Maybe ByteString | Header value if found |
Lookup a particular header from a response.
responseCookieJar :: HttpResponse response => response -> CookieJar Source #
Get the response CookieJar
.
Defining your own interpretation
To create a new response interpretation you just need to make your data
type an instance of the HttpResponse
type class.
class HttpResponse response where Source #
A type class for response interpretations. It allows us to describe how
to consume the response from a
and produce
the final result that is to be returned to the user.Response
BodyReader
type HttpResponseBody response :: Type Source #
The associated type is the type of body that can be extracted from an
instance of HttpResponse
.
toVanillaResponse :: response -> Response (HttpResponseBody response) Source #
The method describes how to get the underlying Response
record.
:: Response BodyReader | Response with body reader inside |
-> IO response | The final result |
This method describes how to consume response body and, more
generally, obtain response
value from
.Response
BodyReader
Note: BodyReader
is nothing but
. You should
call this action repeatedly until it yields the empty IO
ByteString
ByteString
. In
that case streaming of response is finished (which apparently leads to
closing of the connection, so don't call the reader after it has
returned the empty ByteString
once) and you can concatenate the
chunks to obtain the final result. (Of course you could as well stream
the contents to a file or do whatever you want.)
Note: signature of this function was changed in the version 1.0.0.
acceptHeader :: Proxy response -> Maybe ByteString Source #
The value of "Accept"
header. This is useful, for example, if a
website supports both XML
and JSON
responses, and decides what to
reply with based on what Accept
headers you have sent.
Note: manually specified Options
that set the "Accept"
header
will take precedence.
Since: 2.1.0
Instances
HttpResponse BsResponse Source # | |
Defined in Network.HTTP.Req | |
HttpResponse IgnoreResponse Source # | |
HttpResponse LbsResponse Source # | |
Defined in Network.HTTP.Req | |
HttpResponse (Response ()) Source # | This instance has been added to make it easier to inspect Since: 3.12.0 |
Defined in Network.HTTP.Req type HttpResponseBody (Response ()) Source # toVanillaResponse :: Response () -> Response (HttpResponseBody (Response ())) Source # getHttpResponse :: Response BodyReader -> IO (Response ()) Source # acceptHeader :: Proxy (Response ()) -> Maybe ByteString Source # | |
FromJSON a => HttpResponse (JsonResponse a) Source # | |
Defined in Network.HTTP.Req type HttpResponseBody (JsonResponse a) Source # toVanillaResponse :: JsonResponse a -> Response (HttpResponseBody (JsonResponse a)) Source # getHttpResponse :: Response BodyReader -> IO (JsonResponse a) Source # acceptHeader :: Proxy (JsonResponse a) -> Maybe ByteString Source # |
Other
data HttpException Source #
Exceptions that this library throws.
VanillaHttpException HttpException | A wrapper with an |
JsonHttpException String | A wrapper with Aeson-produced |
Instances
Exception HttpException Source # | |
Defined in Network.HTTP.Req | |
Generic HttpException Source # | |
Defined in Network.HTTP.Req type Rep HttpException :: Type -> Type # from :: HttpException -> Rep HttpException x # to :: Rep HttpException x -> HttpException # | |
Show HttpException Source # | |
Defined in Network.HTTP.Req showsPrec :: Int -> HttpException -> ShowS # show :: HttpException -> String # showList :: [HttpException] -> ShowS # | |
type Rep HttpException Source # | |
Defined in Network.HTTP.Req type Rep HttpException = D1 ('MetaData "HttpException" "Network.HTTP.Req" "req-3.13.3-HNskJKOXnhK1SbK2hnOo99" 'False) (C1 ('MetaCons "VanillaHttpException" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 HttpException)) :+: C1 ('MetaCons "JsonHttpException" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 String))) |
isStatusCodeException :: HttpException -> Maybe (Response ()) Source #
Return Just
if the given HttpException
is wrapping a http-client's
StatusCodeException
. Otherwise, return Nothing
.
Since: 3.12.0
data CanHaveBody Source #
A simple type isomorphic to Bool
that we only have for better error
messages. We use it as a kind and its data constructors as type-level
tags.
See also: HttpMethod
and HttpBody
.
CanHaveBody | Indeed can have a body |
NoBody | Should not have a body |
A type-level tag that specifies URL scheme used (and thus if HTTPS is
enabled). This is used to force TLS requirement for some authentication
Option
s.
Instances
Data Scheme Source # | |
Defined in Network.HTTP.Req gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> Scheme -> c Scheme # gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c Scheme # toConstr :: Scheme -> Constr # dataTypeOf :: Scheme -> DataType # dataCast1 :: Typeable t => (forall d. Data d => c (t d)) -> Maybe (c Scheme) # dataCast2 :: Typeable t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c Scheme) # gmapT :: (forall b. Data b => b -> b) -> Scheme -> Scheme # gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> Scheme -> r # gmapQr :: forall r r'. (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> Scheme -> r # gmapQ :: (forall d. Data d => d -> u) -> Scheme -> [u] # gmapQi :: Int -> (forall d. Data d => d -> u) -> Scheme -> u # gmapM :: Monad m => (forall d. Data d => d -> m d) -> Scheme -> m Scheme # gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> Scheme -> m Scheme # gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> Scheme -> m Scheme # | |
Generic Scheme Source # | |
Show Scheme Source # | |
Eq Scheme Source # | |
Ord Scheme Source # | |
Lift Scheme Source # | |
type Rep Scheme Source # | |