@@ -7,73 +7,77 @@
77-- Stability : experimental
88-- Portability : portable
99--
10−-- The documentation below is structured in such a way that most important
11−-- information goes first: you learn how to do HTTP requests, then how to
12−-- embed them in any monad you have, then it goes on giving you details
13−-- about less-common things you may want to know about. The documentation is
14−-- written with sufficient coverage of details and examples, it's designed
15−-- to be a complete tutorial on its own.
10+-- The documentation below is structured in such a way that the most
11+-- important information is presented first: you learn how to do HTTP
12+-- requests, how to embed them in any monad you have, and then it gives you
13+-- details about less-common things you may want to know about. The
14+-- documentation is written with sufficient coverage of details and
15+-- examples, and it's designed to be a complete tutorial on its own.
1616--
1717-- /(A modest intro goes here, click on 'req' to start making requests.)/
1818--
1919-- === About the library
2020--
21−-- This is an easy-to-use, type-safe, expandable, high-level HTTP library
21+-- Req is an easy-to-use, type-safe, expandable, high-level HTTP library
2222-- that just works without any fooling around.
2323--
24−-- What does the “easy-to-use” phrase mean? It means that the library is
25−-- designed to be beginner-friendly, so it's simple to add it to your monad
24+-- What does the phrase “easy-to-use” mean? It means that the library is
25+-- designed to be beginner-friendly so it's simple to add to your monad
2626-- stack, intuitive to work with, well-documented, and does not get in your
27−-- way. Doing HTTP requests is a common task and Haskell library for this
27+-- way. Doing HTTP requests is a common task and a Haskell library for this
2828-- should be very approachable and clear to beginners, thus certain
2929-- compromises were made. For example, one cannot currently modify
30−-- 'L.ManagerSettings' of default manager because the library always uses
31−-- the same implicit global manager for simplicity and maximal connection
32−-- sharing. There is a way to use your own manager with different settings,
33−-- but it requires a bit more typing.
30+-- 'L.ManagerSettings' of the default manager because the library always
31+-- uses the same implicit global manager for simplicity and maximal
32+-- connection sharing. There is a way to use your own manager with different
33+-- settings, but it requires a bit more typing.
3434--
3535-- “Type-safe” means that the library is protective and eliminates certain
36−-- class of errors. For example, we have correct-by-construction 'Url's,
37−-- it's guaranteed that user does not send request body when using methods
38−-- like 'GET' or 'OPTIONS', amount of implicit assumptions is minimized by
39−-- making user specify his\/her intentions in explicit form (for example,
40−-- it's not possible to avoid specifying body or method of a request).
41−-- Authentication methods that assume TLS force user to use TLS on type
42−-- level. The library carefully hides underlying types from lower-level
43−-- @http-client@ package because it's not safe enough (for example
44−-- 'L.Request' is an instance of 'Data.String.IsString' and if it's
45−-- malformed, it will blow up at run-time).
36+-- classes of errors. For example, we have correct-by-construction 'Url's,
37+-- it's guaranteed that the user does not send the request body when using
38+-- methods like 'GET' or 'OPTIONS', and the amount of implicit assumptions
39+-- is minimized by making the user specify his\/her intentions in an
40+-- explicit form (for example, it's not possible to avoid specifying the
41+-- body or method of a request). Authentication methods that assume TLS
42+-- force the user to use TLS at the type level. The library also carefully
43+-- hides underlying types from the lower-level @http-client@ package because
44+-- those types are not safe enough (for example 'L.Request' is an instance
45+-- of 'Data.String.IsString' and, if it's malformed, it will blow up at
46+-- run-time).
4647--
4748-- “Expandable” refers to the ability of the library to be expanded without
48−-- ugly hacking. For example, it's possible to define your own HTTP methods,
49−-- new ways to construct body of request, new authorization options, new
50−-- ways to actually perform request and how to represent\/parse response. As
51−-- user extends the library to satisfy his\/her special needs, the new
52−-- solutions work just like built-ins. That said, all common cases are
53−-- covered by the library out-of-the-box.
49+-- having to resort to ugly hacking. For example, it's possible to define
50+-- your own HTTP methods, create new ways to construct the body of a
51+-- request, create new authorization options, perform a request in a
52+-- different way, and create your own methods to parse and represent a
53+-- response. As a user extends the library to satisfy his\/her special
54+-- needs, the new solutions will work just like the built-ins. However, all
55+-- of the common cases are also covered by the library out-of-the-box.
5456--
5557-- “High-level” means that there are less details to worry about. The
56−-- library is a result of my experiences as a Haskell consultant, working
57−-- for several clients who have very different projects and so the library
58−-- adapts easily to any particular style of writing Haskell applications.
59−-- For example, some people prefer throwing exceptions, while others are
60−-- concerned with purity: just define 'handleHttpException' accordingly when
61−-- making your monad instance of 'MonadHttp' and it will play seamlessly.
62−-- Finally, the library cuts boilerplate considerably and helps write
63−-- concise, easy to read and maintain code.
58+-- library is a result of my experiences as a Haskell consultant. Working
59+-- for several clients, who had very different projects, showed me that the
60+-- library should adapt easily to any particular style of writing Haskell
61+-- applications. For example, some people prefer throwing exceptions, while
62+-- others are concerned with purity. Just define 'handleHttpException'
63+-- accordingly when making your monad instance of 'MonadHttp' and it will
64+-- play together seamlessly. Finally, the library cuts boilerplate down
65+-- considerably, and helps you write concise, easy to read, and maintainable
66+-- code.
6467--
6568-- === Using with other libraries
6669--
67−-- * You won't need low-level interface of @http-client@ most of the
68−-- time, but when you do, it's better import it qualified because it
69−-- has naming conflicts with @req@.
70−-- * For streaming of large request bodies see companion package
70+-- * You won't need the low-level interface of @http-client@ most of the
71+-- time, but when you do, it's better to do a qualified import,
72+-- because @http-client@ has naming conflicts with @req@.
73+-- * For streaming of large request bodies see the companion package
7174-- @req-conduit@: <https://hackage.haskell.org/package/req-conduit>.
7275--
7376-- === Lightweight, no risk solution
7477--
7578-- The library uses the following mature packages under the hood to
76−-- guarantee you best experience without bugs or other funny business:
79+-- guarantee you the best experience that doesn't have any bugs or other
80+-- funny business:
7781--
7882-- * <https://hackage.haskell.org/package/http-client> — low level HTTP
7983-- client used everywhere in Haskell.
@@ -81,9 +85,9 @@
8185-- support for @http-client@.
8286--
8387-- It's important to note that since we leverage well-known libraries that
84−-- the whole Haskell ecosystem uses, there is no risk in using @req@, as the
88+-- the whole Haskell ecosystem uses, there is no risk in using @req@. The
8589-- machinery for performing requests is the same as with @http-conduit@ and
86−-- @wreq@, it's just the API is different.
90+-- @wreq@. The only difference is the API.
8791
8892{-# LANGUAGE CPP #-}
8993{-# LANGUAGE DataKinds #-}