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 HTTP request, out-of-the-box it can be the following: ignoreResponse, jsonResponse, bsResponse (to get strict ByteString), lbsResponse (to get lazy ByteString), and returnRequest (makes no request, just returns response, used for testing).

Finally options is a Monoid that holds a composite Option for all other optional things like query parameters, headers, non-standard port number, etc. There are quite a few things you can put there, see 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 very quickly.

Examples

{-# LANGUAGE OverloadedStrings #-}

module Main (main) where

import Control.Exception (throwIO)
import Control.Monad
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

instance MonadHttp IO where
  handleHttpException = throwIO

main :: IO ()
main = do
  let n :: Int
      n = 5
  bs <- req GET (https "httpbin.org" /: "bytes" /~ n) NoReqBody bsResponse mempty
  B.putStrLn (responseBody bs)

main :: IO ()
main = do
  let n, seed :: Int
      n    = 5
      seed = 100
  bs <- req GET (https "httpbin.org" /: "bytes" /~ n) NoReqBody bsResponse $
    "seed" =: seed
  B.putStrLn (responseBody bs)

data MyData = MyData
  { size  :: Int
  , color :: Text
  } deriving (Show, Generic)

instance ToJSON MyData
instance FromJSON MyData

main :: IO ()
main = do
  let myData = MyData
        { size  = 6
        , color = "Green" }
  v <- req POST (https "httpbin.org" /: "post") (ReqBodyJson myData) jsonResponse mempty
  print (responseBody v :: Value)

main :: IO ()
main = do
  let params =
        "foo" =: ("bar" :: Text) <>
        queryFlag "baz"
  response <- req POST (https "httpbin.org" /: "post") (ReqBodyUrlEnc params) jsonResponse mempty
  print (responseBody response :: Value)

main :: IO ()
main = 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'.
  let (url, options) = fromJust (parseUrlHttps "https://httpbin.org/get?foo=bar")
  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
  print (responseBody response :: Value)

Perform an action using 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.

GET method.

POST method.

HEAD method.

PUT method.

DELETE method. This data type does not allow having request body with DELETE requests, as it should be, however some APIs may expect DELETE requests to have bodies, in that case define your own variation of DELETE method and allow it to have a body.

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 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 have “http” as its scheme and empty path. This also sets port to 80.

Given host name, produce a Url which have “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 cases when next URL piece is a Text literal.

The parseUrlHttp function provides an alternative method to get Url (possibly with some Options) from a ByteString. This is useful when you are given a URL to query dynamically and don't know it beforehand. The function parses ByteString because it's the correct type to represent a URL, as Url cannot contain characters outside of ASCII range, thus we can consider every character a Word8 value.

This function only parses Url (scheme, host, path) and optional query parameters that are returned as Option. It does not parse method name or authentication info from given ByteString.

Just like parseUrlHttp, but expects “https” scheme.

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-from-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 type ReqBodyMultipart, as its constructor is not exported on purpose.

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 HTTP RequestBody.

The type function recognizes NoReqBody as having NoBody, while any other body option CanHaveBody. This forces user to use NoReqBody with GET method and other methods that should not send a body.

This type function allows any HTTP body if method says it CanHaveBody. When method says it should have NoBody, the only body option to use is NoReqBody.

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

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 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, 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

A type class for query-parameter-like things. The reason to have 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.

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.

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.

Specify the port to connect to explicitly. Normally, Url you use determines default port, 80 for HTTP and 443 for HTTPS, this Option allows to choose 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 number of microseconds to wait for response. Default is 30 seconds.

HTTP version to send to server, default is HTTP 1.1.

Make a request and ignore body of response.

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

Make a request and interpret body of 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 (JsonHttpException constructor will be used).

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

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

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

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

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

This interpretation does not result in any call at all, but you can use the responseRequest function to extract Request that req has prepared. This is useful primarily for testing.

Note that when you use this interpretation inspecting response will diverge (i.e. it'll blow up with an error, don't do that).

Use this as the forth argument of req to specify that you want it to just return the request it consturcted without making any requests.

Get response body.

Get response status code.

Get response status message.

Look a particular header from a response.

Get response CookieJar.

Get the original request from ReturnRequest response interpretation.

A type class for response interpretations. It allows to fully control how request is made and how its body is parsed.

Exceptions that this library throws.

A simple Bool-like type 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 TLS is enabled). This is used to force TLS requirement for some authentication Options.