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 below.

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 strict ByteString)
• lbsResponse (to get a lazy ByteString)

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

{-# 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

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)

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)

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)

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)

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)

A version of req that does not use one of the predefined instances of HttpResponse but instead allows the user to consume Response BodyReader manually, in a custom way.

Since: 1.0.0

A version of req that takes a callback to modify the Request, but otherwise performs the request identically.

Since: 3.7.0

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

Perform an action using the global implicit Manager that the rest of the library uses. This allows to reuse connections that the Manager controls.

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.

HttpConfig contains general and default settings to be used when making HTTP requests.

Default value of HttpConfig.

Since: 2.0.0

A monad that allows to run req in any IO-enabled monad without having to define new instances.

Since: 0.4.0

Run a computation in the Req monad with the given HttpConfig. In case of exceptional situation an HttpException will be thrown.

Since: 0.4.0

GET method.

POST method.

HEAD method.

PUT method.

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.

TRACE method.

CONNECT method.

OPTIONS method.

PATCH method.

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"

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 Urls (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

Given host name, produce a Url which has “http” as its scheme and empty path. This also sets port to 80.

Given host name, produce a Url which has “https” as its scheme and empty path. This also sets port to 443.

Grow 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.

Type-constrained version of (/~) to remove ambiguity in the cases when next URL piece is a Text literal.

The useHttpURI function provides an alternative method to get Url (possibly with some Options) 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

Just like useHttpURI, but expects the “https” scheme.

Since: 3.0.0

A combination of useHttpURI and useHttpsURI for cases when scheme is not known in advance.

Since: 3.0.0

A quasiquoter to build an Url and Option tuple. The type of the generated expression is (Url scheme0, Option scheme1) with scheme0 being either Http or Https depending on the input.

Since: 3.2.0

Render a Url as Text.

Since: 3.4.0

This data type represents empty body of an HTTP request. This is the data type to use with HttpMethods 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.

This body option allows to use a JSON object as 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.

This body option streams request body from a file. It is expected that the file size does not change during the streaming.

Using of this body option does not set the Content-Type header.

HTTP request body represented by a strict ByteString.

Using of this body option does not set the Content-Type header.

HTTP request body represented by a lazy ByteString.

Using of this body option does not set the Content-Type header.

Form 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.

An opaque monoidal value that allows to collect URL-encoded parameters to be wrapped in ReqBodyUrlEnc.

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

Create ReqBodyMultipart request body from a collection of Parts.

Since: 0.2.0

A type class for things that can be interpreted as an HTTP RequestBody.

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.

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.

Note: users of GHC 8.0.1 and later will see a slightly more friendly error message when method does not allow a body and body is provided.

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.

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)

Construct a flag, that is, 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 ())

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.

Create an Option that adds a header. Note that if you mappend two headers with the same names the leftmost header will win. This means, in particular, that you cannot create a request with several headers of the same name.

Attach a header with given name and content to a Request.

Since: 1.1.0

Use the given CookieJar. A CookieJar can be obtained from a Response record.

The Option adds basic authentication.

See also: https://en.wikipedia.org/wiki/Basic_access_authentication.

An alternative to basicAuth which works for any scheme. Note that using basic access authentication without SSL/TLS is vulnerable to attacks. Use basicAuth instead unless you know what you are doing.

Since: 0.3.1

The Option set basic proxy authentication header.

Since: 1.1.0

The Option adds OAuth1 authentication.

Since: 0.2.0

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.

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.

A helper to create custom authentication Options. The given IO-enabled request transformation is applied after all other modifications when constructing a request. Use wisely.

Since: 1.1.0

Specify the port to connect to explicitly. Normally, Url you use determines the default port: 80 for HTTP and 443 for HTTPS. This Option allows to choose an arbitrary port overwriting the defaults.

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.

Make a request and ignore the body of the response.

Use this as the fourth argument of req to specify that you want it to ignore the response body.

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).

Use this as the fourth argument of req to specify that you want it to return the JsonResponse interpretation.

Make a request and interpret the body of the response as a strict ByteString.

Use this as the fourth argument of req to specify that you want to interpret the response body as a strict ByteString.

Make a request and interpret the body of the response as a lazy ByteString.

Use this as the fourth argument of req to specify that you want to interpret the response body as a lazy ByteString.

Get the response body.

Get the response status code.

Get the response status message.

Lookup a particular header from a response.

Get the response CookieJar.

A type class for response interpretations. It allows to describe how to consume response from a Response BodyReader and produce the final result that is to be returned to the user.

Exceptions that this library throws.

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.

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 Options.