An effect for making http requests. @since 0.1.0

See req. @since 0.1.0

Run a Req effect with the defaultHttpConfig. @since 0.1.0

Run a Req effect with a custom HttpConfig. @since 0.1.0

Get the response CookieJar.

Lookup a particular header from a response.

Get the response status message.

Get the response status code.

Get the response body.

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

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

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

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

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

Specify the number of microseconds to wait for response. The default value is 30 seconds (defined in ManagerSettings of connection Manager).

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 port to connect to explicitly. Normally, Url you use determines the default port: 80 for HTTP and 443 for HTTPS. This Option allows us to choose an arbitrary port overwriting the defaults.

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: req-1.1.0

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.

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 OAuth1 authentication.

Since: req-0.2.0

The Option set basic proxy authentication header.

Since: req-1.1.0

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: req-0.3.1

The Option adds basic authentication.

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

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

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

Since: req-1.1.0

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.

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

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)

Create ReqBodyMultipart request body from a collection of Parts.

Since: req-0.2.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: req-3.2.0

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

Since: req-3.0.0

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

Since: req-3.0.0

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: req-3.0.0

Render a Url as Text.

Since: req-3.4.0

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

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.

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

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

The default value of HttpConfig.

Since: req-2.0.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.

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.

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.

HttpConfig contains settings to be used when making HTTP requests.

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.

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.

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

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

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.

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.

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: req-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.

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.

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.

Make a request and ignore the body of the response.

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

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

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

The associated type is the type of body that can be extracted from an instance of HttpResponse.

A type class for response interpretations. It allows us to describe how to consume the 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.