@@ -15,33 +15,34 @@
1515-- What does the “easy-to-use” phrase mean? It means that the library is
1616-- designed to be beginner-friendly, so it's simple to add it to your monad
1717-- stack, intuitive to work with, well-documented, and does not get in your
18−-- way. On this path certain compromises were made. For example one cannot
19−-- currently modify 'L.ManagerSettings' of default manager because the
20−-- library always use the same implicit global manager for simplicity and
21−-- maximal connection sharing. There is a way to use your own manager with
22−-- different settings, but it requires a bit more typing. Doing HTTP
23−-- requests is a common task and Haskell library for this should be very
24−-- approachable and clear to beginners.
18+-- way. Doing HTTP requests is a common task and Haskell library for this
19+-- should be very approachable and clear to beginners. On this path certain
20+-- compromises were made. For example one cannot currently modify
21+-- 'L.ManagerSettings' of default manager because the library always use the
22+-- same implicit global manager for simplicity and maximal connection
23+-- sharing. There is a way to use your own manager with different settings,
24+-- but it requires a bit more typing.
2525--
2626-- “Type-safe” means that the library is protective and eliminates certain
2727-- class of errors compared to alternative libraries like @wreq@ or vanilla
28−-- @http-client@. For example we have correct-by-construction 'Url's, it's
28+-- @http-client@. For example, we have correct-by-construction 'Url's, it's
2929-- guaranteed that user does not send request body when using methods like
30−-- 'GET' or 'DELETE', amount of implicit assumptions is minimized by making
30+-- 'GET' or 'OPTIONS', amount of implicit assumptions is minimized by making
3131-- user specify his\/her intentions in explicit form (for example it's not
32−-- possible to avoid specifying body or method of a request). The library
33−-- carefully hides underlying types from lower-level @http-client@ package
34−-- because it's not type safe enough (for example 'L.Request' is an instance
35−-- of 'Data.String.IsString' and if it's malformed, it will blow up at
36−-- run-time).
32+-- possible to avoid specifying body or method of a request). Authentication
33+-- methods that assume TLS will force user to use TLS on type level. The
34+-- library carefully hides underlying types from lower-level @http-client@
35+-- package because it's not type safe enough (for example 'L.Request' is an
36+-- instance of 'Data.String.IsString' and if it's malformed, it will blow up
37+-- at run-time).
3738--
3839-- “Expandable” refers to the ability of the library to be expanded without
3940-- ugly hacking. For example it's possible to define your own HTTP methods,
4041-- new ways to construct body of request, new authorization options, new
41−-- ways to actually perform request and how to represent\/parse its
42−-- response. As user extends the library to satisfy his\/her special needs,
43−-- the new solutions work just like built-ins. That said, all common cases
44−-- are covered by the library out-of-the-box.
42+-- ways to actually perform request and how to represent\/parse response. As
43+-- user extends the library to satisfy his\/her special needs, the new
44+-- solutions work just like built-ins. That said, all common cases are
45+-- covered by the library out-of-the-box.
4546--
4647-- “High-level” means that there are less details to worry about. The
4748-- library is a result of my experiences as a Haskell consultant, working
@@ -51,7 +52,7 @@
5152-- concerned with purity: just define 'handleHttpException' accordingly when
5253-- making your monad instance of 'MonadHttp' and it will play seamlessly.
5354-- Finally, the library cuts boilerplate considerably and helps write
54−-- concise, easy to read code, thanks to its minimal and uniform API.
55+-- concise, easy to read and maintain code.
5556--
5657-- The documentation below is structured in such a way that most important
5758-- information goes first: you learn how to do HTTP requests, then how to
@@ -68,12 +69,15 @@
6869-- client used everywhere in Haskell.
6970-- * <https://hackage.haskell.org/package/http-client-tls> — TLS (HTTPS)
7071-- support for @http-client@.
71−-- * <https://hackage.haskell.org/package/http-conduit> — conduit
72−-- interface to @http-client@.
7372--
7473-- You won't need low-level interface of @http-client@ most of the time, but
7574-- when you do, it's better import it qualified because it has naming
7675-- conflicts with @req@.
76+--
77+-- Finally, it's important to note that since we leverage other well-known
78+-- libraries that the whole Haskell ecosystem uses, there is no risk in
79+-- using @req@, as the machinery for performing requests is the same as with
80+-- @http-conduit@ and @wreq@, it's just the API is different.
7781
7882{-# LANGUAGE DataKinds #-}
7983{-# LANGUAGE DeriveDataTypeable #-}
@@ -96,7 +100,7 @@ module Network.HTTP.Req
96100 , HttpConfig (..)
97101 -- * Request
98102 -- ** Methods
99− -- $request-methods
103+ -- $methods
100104 , GET (..)
101105 , POST (..)
102106 , HEAD (..)
@@ -108,6 +112,7 @@ module Network.HTTP.Req
108112 , PATCH (..)
109113 , HttpMethod (..)
110114 -- ** URL
115+ -- $url
111116 , Url
112117 , http
113118 , https
@@ -117,17 +122,19 @@ module Network.HTTP.Req
117122 -- ** Body
118123 , HttpBody (..) -- TODO more stuff here
119124 -- ** Optional parameters
120− -- $request-optional-parameters
125+ -- $optional-parameters
121126 , Option
122127 -- *** Query parameters
128+ -- $query-parameters
123129 , (=:)
124130 , queryFlag
125131 , QueryParam (..)
126132 -- *** Headers
127133 , header
128134 -- *** Cookies
135+ -- $cookies
129136 -- *** Authentication
130− -- $request-optional-parameters-authentication
137+ -- $authentication
131138 , basicAuth
132139 , oAuth1
133140 , oAuth2Bearer
@@ -139,8 +146,10 @@ module Network.HTTP.Req
139146 , responseTimeout
140147 , httpVersion
141148 -- * Response
149+ -- $response
142150 , HttpResponse (..)
143151 -- * Other
152+ -- $other
144153 , CanHaveBody (..)
145154 , Scheme (..) )
146155where
@@ -275,14 +284,14 @@ class MonadIO m => MonadHttp m where
275284-- making HTTP requests.
276285
277286data HttpConfig = HttpConfig
278− { httpConfigProxy :: !(Maybe L.Proxy)
287+ { httpConfigProxy :: Maybe L.Proxy
279288 -- ^ Proxy to use. By default values of @HTTP_PROXY@ and @HTTPS_PROXY@
280289 -- environment variables are respected, this setting overwrites them.
281290 -- Default value: 'Nothing'.
282− , httpConfigRedirectCount :: !Word
291+ , httpConfigRedirectCount :: Word
283292 -- ^ How many redirects to follow when getting a resource. Default
284293 -- value: 10.
285− , httpConfigAltManager :: !(Maybe L.Manager)
294+ , httpConfigAltManager :: Maybe L.Manager
286295 -- ^ Alternative 'L.Manager' to use. 'Nothing' (default value) means
287296 -- that default implicit manager will be used (that's what you want in
288297 -- 99% of cases).
@@ -305,7 +314,7 @@ instance Default HttpConfig where
305314 let Y.Status statusCode _ = L.responseStatus response in
306315 unless (200 <= statusCode && statusCode < 300) $ do
307316 chunk <- BL.toStrict <$> L.brReadSome (L.responseBody response) 1024
308− LI.throwHttp (L.StatusCodeException (() <$ response) chunk) }
317+ LI.throwHttp (L.StatusCodeException (void response) chunk) }
309318
310319instance RequestComponent HttpConfig where
311320 getRequestMod HttpConfig {..} = Endo $ \x ->
@@ -317,9 +326,9 @@ instance RequestComponent HttpConfig where
317326----------------------------------------------------------------------------
318327-- Request — Methods
319328
320−-- $request-methods
329+-- $methods
321330--
322−-- The package provides all methods as defined by RFC 2616, and 'PATCH'
331+-- The package supports all methods as defined by RFC 2616, and 'PATCH'
323332-- which is defined by RFC 5789 — that should be enough to talk to RESTful
324333-- APIs. In some cases however, you may want to add more methods (e.g. you
325334-- work with WebDAV <https://en.wikipedia.org/wiki/WebDAV>); no need to
@@ -358,7 +367,10 @@ instance HttpMethod PUT where
358367 type AllowsBody PUT = 'CanHaveBody
359368 httpMethodName Proxy = Y.methodPut
360369
361−-- | 'DELETE' method.
370+-- | 'DELETE' method. This data type does not allow having request body with
371+-- 'DELETE' requests, as it should be, however some APIs may expect 'DELETE'
372+-- requests to have bodies, in that case define your own variation of
373+-- 'DELETE' method and allow it having a body.
362374
363375data DELETE = DELETE
364376
@@ -427,9 +439,14 @@ instance HttpMethod method => RequestComponent (Womb "method" method) where
427439----------------------------------------------------------------------------
428440-- Request — URL
429441
442+-- $url
443+--
444+-- We use 'Url's which are correct by construction, see 'Url'. To build a
445+-- 'Url' from 'ByteString', use 'parseUrlHttp' or 'parseUrlHttps'.
446+
430447-- | Request's 'Url'. Start constructing your 'Url' with 'http' or 'https'
431448-- specifying the scheme and host at the same time. Then use the @('/:')@
432−-- constructor to grow path one piece at a time. Every single piece of path
449+-- operator to grow path one piece at a time. Every single piece of path
433450-- will be url(percent)-encoded, so @('/:')@ is the only way to have forward
434451-- slashes between path segments. This approach makes working with dynamic
435452-- path segments easy and safe. See examples below how to represent various
@@ -540,7 +557,7 @@ instance HttpBody b => RequestComponent (Womb "body" b) where
540557----------------------------------------------------------------------------
541558-- Request — Optional parameters
542559
543−-- $request-optional-parameters
560+-- $optional-parameters
544561--
545562-- Optional parameters to a request include things like query parameters,
546563-- headers, port number, etc. All optional parameters have the type
@@ -597,6 +614,10 @@ instance RequestComponent (Option scheme) where
597614----------------------------------------------------------------------------
598615-- Request — Optional parameters — Query Parameters
599616
617+-- $query-parameters
618+--
619+-- Something.
620+
600621-- | This operator builds a query parameter that will be included in URL of
601622-- your request after question sign @?@. This is the same syntax you use
602623-- with form URL encoded request bodies.
@@ -659,12 +680,12 @@ attachHeader name value x =
659680----------------------------------------------------------------------------
660681-- Request — Optional parameters — Cookies
661682
662−-- TODO No idea right now.
683+-- $cookies
663684
664685----------------------------------------------------------------------------
665686-- Request — Optional parameters — Authentication
666687
667−-- $request-optional-parameters-authentication
688+-- $authentication
668689--
669690-- TODO Something. You should always prefer authentication 'Option's to
670691-- manual construction of headers, etc., because it's a better style and
@@ -782,6 +803,10 @@ httpVersion major minor = withRequest $ \x ->
782803----------------------------------------------------------------------------
783804-- Response
784805
806+-- $response
807+--
808+-- Something.
809+
785810-- Here we need to provide various options how to consume responses.
786811
787812class HttpResponse response where
@@ -792,6 +817,10 @@ class HttpResponse response where
792817----------------------------------------------------------------------------
793818-- Other
794819
820+-- $other
821+--
822+-- Just some auxiliary definitions.
823+
795824-- | The main class for things that are “parts” of 'L.Request' in the sense
796825-- that if we have a 'L.Request', then we know how to apply an instance of
797826-- 'RequestComponent' changing\/overwriting something in it. 'Endo' is