The documentation below is structured in such a way that most important information goes first: you learn how to do HTTP requests, then how to embed them in any monad you have, then it goes on giving you details about less-common things you may want to know about. The documentation is written with sufficient coverage of details and examples, it's designed to be a complete tutorial on its own.

(A modest intro goes here, click on req to start making requests.)

About the library

This is an easy-to-use, type-safe, expandable, high-level HTTP library that just works without any fooling around.

What does the “easy-to-use” phrase mean? It means that the library is designed to be beginner-friendly, so it's simple to add it to your monad stack, intuitive to work with, well-documented, and does not get in your way. Doing HTTP requests is a common task and Haskell library for this should be very approachable and clear to beginners, thus certain compromises were made. For example, one cannot currently modify ManagerSettings of default manager because the library always uses the same implicit global manager for simplicity and maximal connection sharing. There is a way to use your own manager with different settings, but it requires a bit more typing.

“Type-safe” means that the library is protective and eliminates certain class of errors. For example, we have correct-by-construction Url s, it's guaranteed that user does not send request body when using methods like GET or OPTIONS , amount of implicit assumptions is minimized by making user specify his/her intentions in explicit form (for example, it's not possible to avoid specifying body or method of a request). Authentication methods that assume TLS force user to use TLS on type level. The library carefully hides underlying types from lower-level http-client package because it's not safe enough (for example Request is an instance of IsString and if it's malformed, it will blow up at run-time).

“Expandable” refers to the ability of the library to be expanded without ugly hacking. For example, it's possible to define your own HTTP methods, new ways to construct body of request, new authorization options, new ways to actually perform request and how to represent/parse response. As user extends the library to satisfy his/her special needs, the new solutions work just like built-ins. That said, all common cases are covered by the library out-of-the-box.

“High-level” means that there are less details to worry about. The library is a result of my experiences as a Haskell consultant, working for several clients who have very different projects and so the library adapts easily to any particular style of writing Haskell applications. For example, some people prefer throwing exceptions, while others are concerned with purity: just define handleHttpException accordingly when making your monad instance of MonadHttp and it will play seamlessly. Finally, the library cuts boilerplate considerably and helps write concise, easy to read and maintain code.

Using with other libraries

You won't need low-level interface of http-client most of the time, but when you do, it's better import it qualified because it has naming conflicts with req .

most of the time, but when you do, it's better import it qualified because it has naming conflicts with . For streaming of large request bodies see companion package req-conduit : https://hackage.haskell.org/package/req-conduit.

Lightweight, no risk solution

The library uses the following mature packages under the hood to guarantee you best experience without bugs or other funny business:

https://hackage.haskell.org/package/http-client — low level HTTP client used everywhere in Haskell.

https://hackage.haskell.org/package/http-client-tls — TLS (HTTPS) support for http-client .