% wreq: a Haskell web client library
% HTTP made easy for Haskell.
  <a href="tutorial.html" class="btn btn-primary btn-lg" role="button">Tutorial</a>



`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`](http://hackage.haskell.org/package/http-client/)
  and [`lens`](https://lens.github.io/)

* 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.](https://www.runscope.com) Traffic Inspector

# Whirlwind tour

All of the examples that follow assume that you are using the
[`OverloadedStrings`](https://downloads.haskell.org/~ghc/latest/docs/html/users_guide/type-class-extensions.html#overloaded-strings)
language extension, which you can enable in `ghci` as follows:

~~~~ {.haskell}
ghci> :set -XOverloadedStrings
~~~~

And now let's get started.

~~~~ {.haskell}
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](tutorial.html#a-quick-lens-backgrounder)) and
powerful to work with.

~~~~ {.haskell}
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.

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

~~~~ {.haskell}
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.

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

Easily write
[`attoparsec`](http://hackage.haskell.org/package/attoparsec) parsers
on the spot, to safely and reliably deal with complicated headers and
bodies.

~~~~ {.haskell}
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.


<div class="jumbotron" style="margin-top: 40px;">
<h2 style="margin-top: 20px;">Ready to jump in?</h2>

We've worked hard to make `wreq` quick to learn.

<a href="tutorial.html" class="btn btn-success btn-lg" role="button">Tutorial</a>

We're proud of the example-filled docs.

<a href="http://hackage.haskell.org/package/wreq" class="btn btn-info btn-lg" role="button">Documentation</a>

If you run into problems, let us know.

<a href="https://github.com/bos/wreq" class="btn btn-warning btn-lg" role="button">Issues</a>

</div>


# Acknowledgments

I'd like to thank Edward Kmett and Shachaf Ben-Kiki for tirelessly
answering my never-ending stream of
[lens](https://lens.github.io/)-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](http://hackage.haskell.org/package/http-client) package.

Finally, thanks to Kenneth Reitz for building the indispensable
[httpbin.org](http://httpbin.org/) HTTP testing service, and of course
for his [requests library](http://docs.python-requests.org/en/latest/).