Maintenance status: I no longer actively maintain this software. Expect details here to be outdated.

wreq is an HTTP client library that aims to be pleasant, pragmatic, and type-safe. It builds on top of modern HTTP primitives to give you a clean, high-level API for working with web services.

Features

  • A single, straightforward interface for making requests and handling responses.
  • Built-in JSON, form, and multipart helpers.
  • Automatic session handling with cookies.
  • Lens-based accessors to traverse and update response data.
  • Tested against a wide range of HTTP scenarios.

Installation

Install from Hackage with cabal (or stack, if you prefer):

cabal update
cabal install wreq

or

stack update
stack install wreq

To work with the development version:

git clone https://github.com/haskell/wreq.git
cd wreq
cabal build

Usage

At its simplest, wreq takes away the ceremony. Fetching a URL and inspecting its status code and body is just:

{-# LANGUAGE OverloadedStrings #-}
import Control.Lens
import Network.Wreq

main :: IO ()
main = do
  r <- get "https://httpbin.org/get"
  print (r ^. responseStatus . statusCode)
  print (r ^. responseBody)

Need to post some JSON?

{-# LANGUAGE OverloadedStrings #-}
import Control.Lens
import Data.Aeson (object, (.=))
import Network.Wreq

main :: IO ()
main = do
  let payload = object ["name" .= ("criterion" :: String), "version" .= ("1.6.3.0" :: String)]
  r <- post "https://httpbin.org/post" payload
  print (r ^. responseStatus . statusCode)

Do you want to re-use settings such as headers, timeouts, or cookies? Create a Session, and wreq will manage them for you:

{-# LANGUAGE OverloadedStrings #-}
import Control.Lens
import Network.Wreq

main :: IO ()
main = do
  sess <- newSession
  let opts = defaults & header "User-Agent" .~ ["wreq-example"]
  r <- customMethodWith "PATCH" "https://httpbin.org/patch" opts sess
  print (r ^. responseStatus . statusCode)

Check out the examples directory for more complete programs, including multipart uploads, streaming, and interacting with JSON APIs.

Learn more

  • Tutorial – learn the basics, from simple GETs to streaming and session management.
  • Hackage package page – reference API documentation, release notes, and metadata.
  • Examples – runnable code that explores many common tasks.
  • Issue tracker – report bugs or request features.

Acknowledgments

I would like to thank Edward Kmett and Shachaf Ben-Kiki for tirelessly answering a never-ending stream of lens questions in #haskell-lens.

Thanks also to Michael Snoyman for his quick, helpful responses to bug reports and pull requests against the excellent http-client package.