wreq is a library that makes HTTP client programming in Haskell easy.

Features

• Simple but powerful lens-based API

• Over 100 tests, and built on reliable libraries like http-client and lens

• Session handling includes connection keep-alive and pooling, and cookie persistence

• Automatic decompression

• Powerful multipart form and file upload handling

• Support for JSON requests and responses, including navigation of schema-less responses

• Basic and OAuth2 bearer authentication

• Amazon Web Services (AWS) request signing (Version 4)

• AWS signing supports sending requests through the Runscope Inc. Traffic Inspector

Whirlwind tour

All of the examples that follow assume that you are using the OverloadedStrings language extension, which you can enable in ghci as follows:

ghci> :set -XOverloadedStrings

And now let’s get started.

ghci> import Network.Wreq
ghci> r <- get "http://httpbin.org/get"

The wreq library’s lens-based API is easy to learn (the tutorial walks you through the basics of lenses) and powerful to work with.

ghci> import Control.Lens
ghci> r ^. responseHeader "Content-Type"
"application/json"

Safely and sanely add query parameters to URLs. Let’s find the most popular implementations of Tetris in Haskell.

ghci> let opts = defaults & param "q" .~ ["tetris"]
                          & param "language" .~ ["haskell"]
ghci> r <- getWith opts "https://api.github.com/search/repositories"

Haskell-to-JSON interoperation is seamless.

ghci> import GHC.Generics
ghci> import Data.Aeson
ghci> :set -XDeriveGeneric

ghci> data Addr = Addr Int String deriving (Generic)
ghci> instance ToJSON Addr

ghci> let addr = Addr 1600 "Pennsylvania"
ghci> post "http://httpbin.org/post" (toJSON addr)

Work easily with schemaless JSON APIs. This traverses the complex JSON search result we just received from GitHub above, and pulls out the authors of our popular Tetris clones.

ghci> import Data.Aeson.Lens
ghci> r ^.. responseBody . key "items" . values .
            key "owner" . key "login" . _String
["steffi2392","rmies","Spacejoker","walpen",{-...-}

Easily write attoparsec parsers on the spot, to safely and reliably deal with complicated headers and bodies.

ghci> import Data.Attoparsec.ByteString.Char8 as A
ghci> import Data.List (sort)

ghci> let comma = skipSpace >> "," >> skipSpace
ghci> let verbs = A.takeWhile isAlpha_ascii `sepBy` comma

ghci> r <- options "http://httpbin.org/get"
ghci> r ^. responseHeader "Allow" . atto verbs . to sort
ghci> ["GET","HEAD","OPTIONS"]

There’s a lot more, but why not jump in and start coding. In fact, if you’d like to add new features, that would be great! We love pull requests.

Acknowledgments

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

I also want to thank Michael Snoyman for being so quick with helpful responses to bug reports and pull requests against his excellent http-client package.

Finally, thanks to Kenneth Reitz for building the indispensable httpbin.org HTTP testing service, and of course for his requests library.