git.iko.soy/typeable/req
on 4419835 help sign in
typeable/req/README.md
110 lines 4.5 kB history raw
1# Req
3[![License BSD3](https://img.shields.io/badge/license-BSD3-brightgreen.svg)](http://opensource.org/licenses/BSD-3-Clause)
4[![Hackage](https://img.shields.io/hackage/v/req.svg?style=flat)](https://hackage.haskell.org/package/req)
5[![Stackage Nightly](http://stackage.org/package/req/badge/nightly)](http://stackage.org/nightly/package/req)
6[![Stackage LTS](http://stackage.org/package/req/badge/lts)](http://stackage.org/lts/package/req)
7![CI](https://github.com/mrkkrp/req/workflows/CI/badge.svg?branch=master)
9* [Related packages](#related-packages)
10* [Blog posts](#blog-posts)
11* [Contribution](#contribution)
12* [License](#license)
14```haskell
15{-# LANGUAGE OverloadedStrings #-}
17module Main (main) where
19import Control.Monad.IO.Class
20import Data.Aeson
21import Network.HTTP.Req
23main :: IO ()
24-- You can either make your monad an instance of 'MonadHttp', or use
25-- 'runReq' in any IO-enabled monad without defining new instances.
26main = runReq defaultHttpConfig $ do
27 let payload =
28 object
29 [ "foo" .= (10 :: Int),
30 "bar" .= (20 :: Int)
31 ]
32 -- One function—full power and flexibility, automatic retrying on timeouts
33 -- and such, automatic connection sharing.
34 r <-
35 req
36 POST -- method
37 (https "httpbin.org" /: "post") -- safe by construction URL
38 (ReqBodyJson payload) -- use built-in options or add your own
39 jsonResponse -- specify how to interpret response
40 mempty -- query params, headers, explicit port number, etc.
41 liftIO $ print (responseBody r :: Value)
42```
44Req is an HTTP client library that attempts to be easy-to-use, type-safe,
45and expandable.
47“Easy-to-use” means that the library is designed to be beginner-friendly so
48it's simple to add to your monad stack, intuitive to work with,
49well-documented, and does not get in your way. Doing HTTP requests is a
50common task and a Haskell library for this should be approachable and clear
51to beginners, thus certain compromises were made. For example, one cannot
52currently modify `ManagerSettings` of the default manager because the
53library always uses the same implicit global manager for simplicity and
54maximal connection sharing. There is a way to use your own manager with
55different settings, but it requires more typing.
57“Type-safe” means that the library tries to eliminate certain classes of
58errors. For example, we have correct-by-construction URLs; it is guaranteed
59that the user does not send the request body when using methods like GET or
60OPTIONS, and the amount of implicit assumptions is minimized by making the
61user specify their intentions in an explicit form. For example, it's not
62possible to avoid specifying the body or the method of a request.
63Authentication methods that assume HTTPS force the user to use HTTPS at the
64type level.
66“Expandable” refers to the ability to create new components without having
67to resort to hacking. For example, it's possible to define your own HTTP
68methods, create new ways to construct the body of a request, create new
69authorization options, perform a request in a different way, and create your
70own methods to parse a response.
72The library uses the following mature packages under the hood to guarantee
73you the best experience:
75* [`http-client`](https://hackage.haskell.org/package/http-client)—low level
76 HTTP client used everywhere in Haskell.
77* [`http-client-tls`](https://hackage.haskell.org/package/http-client-tls)—TLS
78 (HTTPS) support for `http-client`.
80It is important to note that since we leverage well-known libraries that the
81whole Haskell ecosystem uses, there is no risk in using Req. The machinery
82for performing requests is the same as with `http-conduit` and Wreq. The
83only difference is the API.
85## Related packages
87The following packages are designed to be used with Req:
89* [`req-conduit`](https://hackage.haskell.org/package/req-conduit)—support
90 for streaming request and response bodies in constant memory.
92If you happen to have written a package that adds new features to Req,
93please submit a PR to include it in this list.
95## Blog posts
97* [Req 1.0.0, HTTP client, and streaming](https://markkarpov.com/post/req-1.0.0-http-client-and-streaming.html)
99## Contribution
101Issues, bugs, and questions may be reported in [the GitHub issue tracker for
102this project](https://github.com/mrkkrp/req/issues).
104Pull requests are also welcome.
106## License
108Copyright © 2016–present Mark Karpov
110Distributed under BSD 3 clause license.