Copyright	(c) 2014 Bryan O'Sullivan
License	BSD-style
Maintainer	bos@serpentine.com
Stability	experimental
Portability	GHC
Safe Haskell	None
Language	Haskell98

Network.Wreq

Contents

HTTP verbs
Incremental consumption of responses
- GET
Configuration
Payloads for POST and PUT
- URL-encoded form data
- Multipart form data
  - Smart constructors
Responses
- Link headers
- Decoding responses
Cookies
Parsing responses

Description

A library for client-side HTTP requests, focused on ease of use.

When reading the examples in this module, you should assume the following environment:

-- Make it easy to write literal ByteString and Text values.
{-# LANGUAGE OverloadedStrings #-}

-- Our handy module.
import Network.Wreq

-- Operators such as (&) and (.~).
import Control.Lens

-- Conversion of Haskell values to JSON.
import Data.Aeson (toJSON)

-- Easy traversal of JSON data.
import Data.Aeson.Lens (key, nth)

There exist some less frequently used lenses that are not exported from this module; these can be found in Network.Wreq.Lens.

Synopsis

HTTP verbs

Sessions

The basic HTTP functions (get, post, and so on) in this module have a few key drawbacks:

If several requests go to the same server, there is no reuse of TCP connections.
There is no management of cookies across multiple requests.

This makes these functions inefficient and verbose for many common uses. For greater efficiency, use the Network.Wreq.Session module.

GET

get :: String -> IO (Response ByteString) Source

Issue a GET request.

Example:

get "http://httpbin.org/get"

>>> r <- get "http://httpbin.org/get"
>>> r ^. responseStatus . statusCode
200

getWith :: Options -> String -> IO (Response ByteString) Source

Issue a GET request, using the supplied Options.

Example:

let opts = defaults & param "foo" .~ ["bar"]
getWith opts "http://httpbin.org/get"

>>> let opts = defaults & param "foo" .~ ["bar"]
>>> r <- getWith opts "http://httpbin.org/get"
>>> r ^? responseBody . key "url"
Just (String "http://httpbin.org/get?foo=bar")

POST

The Postable class determines which Haskell types can be used as POST payloads.

Part and [Part] give a request body with a Content-Type of multipart/form-data. Constructor functions include partText and partFile.

>>> r <- post "http://httpbin.org/post" (partText "hello" "world")
>>> r ^? responseBody . key "form" . key "hello"
Just (String "world")

(ByteString, ByteString) and FormParam (and lists of each) give a request body with a Content-Type of application/x-www-form-urlencoded. The easiest way to use this is via the (:=) constructor.

>>> r <- post "http://httpbin.org/post" ["num" := 31337, "str" := "foo"]
>>> r ^? responseBody . key "form" . key "num"
Just (String "31337")

The "magical" type conversion on the right-hand side of := above is due to the FormValue class. This package provides sensible instances for the standard string and number types.

The Value type gives a JSON request body with a Content-Type of application/json. Any instance of ToJSON can of course be converted to a Value using toJSON.

>>> r <- post "http://httpbin.org/post" (toJSON [1,2,3])
>>> r ^? responseBody . key "json" . nth 0
Just (Number 1.0)

post :: Postable a => String -> a -> IO (Response ByteString) Source

Issue a POST request.

Example:

post "http://httpbin.org/post" (toJSON [1,2,3])

>>> r <- post "http://httpbin.org/post" (toJSON [1,2,3])
>>> r ^? responseBody . key "json"
Just (Array (fromList [Number 1.0,Number 2.0,Number 3.0]))

postWith :: Postable a => Options -> String -> a -> IO (Response ByteString) Source

Issue a POST request, using the supplied Options.

Example:

let opts = defaults & param "foo" .~ ["bar"]
postWith opts "http://httpbin.org/post" (toJSON [1,2,3])

>>> let opts = defaults & param "foo" .~ ["bar"]
>>> r <- postWith opts "http://httpbin.org/post" (toJSON [1,2,3])
>>> r ^? responseBody . key "url"
Just (String "http://httpbin.org/post?foo=bar")

HEAD

head_ :: String -> IO (Response ()) Source

Issue a HEAD request.

Example:

head_ "http://httpbin.org/get"

>>> r <- head_ "http://httpbin.org/get"
>>> r ^? responseHeader "Content-Type"
Just "application/json"

headWith :: Options -> String -> IO (Response ()) Source

Issue a HEAD request, using the supplied Options.

Example:

let opts = defaults & param "foo" .~ ["bar"]
headWith opts "http://httpbin.org/get"

>>> let opts = defaults & param "foo" .~ ["bar"]
>>> r <- headWith opts "http://httpbin.org/get"
>>> r ^? responseHeader "Connection"
Just "keep-alive"

OPTIONS

options :: String -> IO (Response ()) Source

Issue an OPTIONS request.

Example:

options "http://httpbin.org/get"

See atto for a more complex worked example.

optionsWith :: Options -> String -> IO (Response ()) Source

Issue an OPTIONS request, using the supplied Options.

Example:

let opts = defaults & param "foo" .~ ["bar"]
optionsWith opts "http://httpbin.org/get"

PUT

put :: Putable a => String -> a -> IO (Response ByteString) Source

Issue a PUT request.

putWith :: Putable a => Options -> String -> a -> IO (Response ByteString) Source

Issue a PUT request, using the supplied Options.

DELETE

delete :: String -> IO (Response ByteString) Source

Issue a DELETE request.

Example:

delete "http://httpbin.org/delete"

>>> r <- delete "http://httpbin.org/delete"
>>> r ^. responseStatus . statusCode
200

deleteWith :: Options -> String -> IO (Response ByteString) Source

Issue a DELETE request, using the supplied Options.

Example:

let opts = defaults & redirects .~ 0
deleteWith opts "http://httpbin.org/delete"

>>> let opts = defaults & redirects .~ 0
>>> r <- deleteWith opts "http://httpbin.org/delete"
>>> r ^. responseStatus . statusCode
200

Custom Method

customMethod :: String -> String -> IO (Response ByteString) Source

Issue a custom-method request

Example: customMethod "PATCH" "http://httpbin.org/patch"

>>> r <- customMethod "PATCH" "http://httpbin.org/patch"
>>> r ^. responseStatus . statusCode
200

customMethodWith :: String -> Options -> String -> IO (Response ByteString) Source

Issue a custom request method request, using the supplied Options.

Example:

let opts = defaults & redirects .~ 0
customMethodWith "PATCH" opts "http://httpbin.org/patch"

>>> let opts = defaults & redirects .~ 0
>>> r <- customMethodWith "PATCH" opts "http://httpbin.org/patch"
>>> r ^. responseStatus . statusCode
200

Incremental consumption of responses

GET

foldGet :: (a -> ByteString -> IO a) -> a -> String -> IO a Source

foldGetWith :: Options -> (a -> ByteString -> IO a) -> a -> String -> IO a Source

Configuration

data Options Source

Options for configuring a client.

Instances

Show Options
Typeable * Options

defaults :: Options Source

manager :: Lens' Options (Either ManagerSettings Manager) Source

A lens onto configuration of the connection manager provided by the http-client package.

In this example, we enable the use of OpenSSL for (hopefully) secure connections:

import OpenSSL.Session (context)
import Network.HTTP.Client.OpenSSL

let opts = defaults & manager .~ Left (opensslManagerSettings context)
withOpenSSL $
  getWith opts "https://httpbin.org/get"

In this example, we also set the response timeout to 10000 microseconds:

import OpenSSL.Session (context)
import Network.HTTP.Client.OpenSSL
import Network.HTTP.Client (defaultManagerSettings, managerResponseTimeout)

let opts = defaults & manager .~ Left (opensslManagerSettings context)
                    & manager .~ Left (defaultManagerSettings { managerResponseTimeout = Just 10000 } )

withOpenSSL $
  getWith opts "https://httpbin.org/get"

header :: HeaderName -> Lens' Options [ByteString] Source

A lens onto all headers with the given name (there can legitimately be zero or more).

Example:

let opts = defaults & header "Accept" .~ ["*/*"]
getWith opts "http://httpbin.org/get"

param :: Text -> Lens' Options [Text] Source

A lens onto all query parameters with the given name (there can legitimately be zero or more).

In this example, we construct the query URL "http://httpbin.org/get?foo=bar&foo=quux".

let opts = defaults & param "foo" .~ ["bar", "quux"]
getWith opts "http://httpbin.org/get"

redirects :: Lens' Options Int Source

A lens onto the maximum number of redirects that will be followed before an exception is thrown.

In this example, a HttpException will be thrown with a TooManyRedirects constructor, because the maximum number of redirects allowed will be exceeded.

let opts = defaults & redirects .~ 3
getWith opts "http://httpbin.org/redirect/5"

headers :: Lens' Options [Header] Source

A lens onto all headers (there can legitimately be zero or more).

In this example, we print all the headers sent by default with every request.

print (defaults ^. headers)

params :: Lens' Options [(Text, Text)] Source

A lens onto all query parameters.

cookie :: ByteString -> Traversal' Options Cookie Source

A traversal onto the cookie with the given name, if one exists.

N.B. This is an "illegal" Traversal': we can change the cookieName of the associated Cookie so that it differs from the name provided to this function.

cookies :: Lens' Options CookieJar Source

A lens onto all cookies.

checkStatus :: Lens' Options (Maybe (Status -> ResponseHeaders -> CookieJar -> Maybe SomeException)) Source

A lens to get the optional status check function

Authentication

Do not use HTTP authentication unless you are using TLS encryption. These authentication tokens can easily be captured and reused by an attacker if transmitted in the clear.

data Auth Source

Supported authentication types.

Do not use HTTP authentication unless you are using TLS encryption. These authentication tokens can easily be captured and reused by an attacker if transmitted in the clear.

Instances

Eq Auth
Show Auth
Typeable * Auth

data AWSAuthVersion Source

Constructors

AWSv4

AWS request signing version 4

Instances

Eq AWSAuthVersion
Show AWSAuthVersion

auth :: Lens' Options (Maybe Auth) Source

A lens onto request authentication.