@@ -33,15 +33,14 @@
3333-- but it requires a bit more typing.
3434--
3535-- “Type-safe” means that the library is protective and eliminates certain
36−-- class of errors compared to alternative libraries like @wreq@ or vanilla
37−-- @http-client@ and friends. For example, we have correct-by-construction
38−-- 'Url's, it's guaranteed that user does not send request body when using
39−-- methods like 'GET' or 'OPTIONS', amount of implicit assumptions is
40−-- minimized by making user specify his\/her intentions in explicit form
41−-- (for example, it's not possible to avoid specifying body or method of a
42−-- request). Authentication methods that assume TLS force user to use TLS on
43−-- type level. The library carefully hides underlying types from lower-level
44−-- @http-client@ package because it's not type safe enough (for example
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
4544-- 'L.Request' is an instance of 'Data.String.IsString' and if it's
4645-- malformed, it will blow up at run-time).
4746--
@@ -169,7 +168,6 @@ module Network.HTTP.Req
169168 , responseTimeout
170169 , httpVersion
171170 -- * Response
172− -- $response
173171 -- ** Response interpretations
174172 , IgnoreResponse
175173 , ignoreResponse
@@ -189,6 +187,7 @@ module Network.HTTP.Req
189187 , responseCookieJar
190188 , responseRequest
191189 -- ** Defining your own interpretation
190+ -- $new-response-interpretation
192191 , HttpResponse (..)
193192 -- * Other
194193 , HttpException (..)
@@ -759,8 +758,6 @@ instance HttpBody body => RequestComponent (Womb "body" body) where
759758-- optional parameters like query parameters and headers. See sections below
760759-- to learn which 'Option' primitives are available.
761760
762−-- TODO We need examples here.
763−
764761data Option (scheme :: Scheme) =
765762 Option (Endo (Y.QueryText, L.Request)) (Maybe (Endo L.Request))
766763 -- NOTE 'QueryText' is just [(Text, Maybe Text)], we keep it along with
@@ -880,7 +877,7 @@ attachHeader name value x =
880877--
881878-- Support for cookies is quite minimalistic at the moment, its' possible to
882879-- specify which cookies to send using 'cookieJar' and inspect 'L.Response'
883−-- to extract 'L.CookieJar' from it.
880+-- to extract 'L.CookieJar' from it (see 'responseCookieJar').
884881
885882-- | Use the given 'L.CookieJar'. A 'L.CookieJar' can be obtained from a
886883-- 'L.Response' record.
@@ -901,9 +898,20 @@ cookieJar jar = withRequest $ \x ->
901898-- additional type safety that prevents leaking of credentials in cases when
902899-- authentication relies on TLS for encrypting sensitive data.
903900
901+-- | The 'Option' adds basic authentication.
902+--
903+-- See also: <https://en.wikipedia.org/wiki/Basic_access_authentication>.
904+
905+basicAuth
906+ :: ByteString -- ^ Username
907+ -> ByteString -- ^ Password
908+ -> Option 'Https -- ^ Auth 'Option'
909+basicAuth username password = asFinalizer
910+ (L.applyBasicAuth username password)
911+
904912-- | OAuth 1 authentication 'Option'.
905913--
906−-- See also: <https://en.wikipedia.org/wiki/OAuth>
914+-- See also: <https://en.wikipedia.org/wiki/OAuth>.
907915
908916oAuth1
909917 :: ByteString -- ^ Consumer token
@@ -914,18 +922,6 @@ oAuth1
914922oAuth1 ctoken csecret otoken osecret = asFinalizer
915923 (OAuth1.signRequest ctoken csecret otoken osecret)
916924
917−-- | The 'Option' adds basic authentication. The 'Text' values will be UTF-8
918−-- encoded.
919−--
920−-- See also: <https://en.wikipedia.org/wiki/Basic_access_authentication>
921−
922−basicAuth
923− :: ByteString -- ^ Username
924− -> ByteString -- ^ Password
925− -> Option 'Https -- ^ Auth 'Option'
926−basicAuth username password = asFinalizer
927− (L.applyBasicAuth username password)
928−
929925-- | The 'Option' adds an OAuth2 bearer token. This is treated by many
930926-- services as the equivalent of a username and password.
931927--
@@ -933,7 +929,7 @@ basicAuth username password = asFinalizer
933929--
934930-- > oAuth2Bearer token = header "Authorization" ("Bearer " <> token)
935931--
936−-- See also: <https://en.wikipedia.org/wiki/OAuth>
932+-- See also: <https://en.wikipedia.org/wiki/OAuth>.
937933
938934oAuth2Bearer
939935 :: ByteString -- ^ Token
@@ -949,7 +945,7 @@ oAuth2Bearer token = asFinalizer
949945--
950946-- > oAuth2Token token = header "Authorization" ("token" <> token)
951947--
952−-- See also: <https://developer.github.com/v3/oauth#3-use-the-access-token-to-access-the-api>
948+-- See also: <https://developer.github.com/v3/oauth#3-use-the-access-token-to-access-the-api>.
953949
954950oAuth2Token
955951 :: ByteString -- ^ Token
@@ -959,7 +955,7 @@ oAuth2Token token = asFinalizer
959955
960956-- | The 'Option' adds AWS v4 request signature.
961957--
962−-- See also: <https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html>
958+-- See also: <https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html>.
963959
964960awsAuth
965961 :: ByteString -- ^ AWS access key
@@ -1014,18 +1010,6 @@ httpVersion
10141010httpVersion major minor = withRequest $ \x ->
10151011 x { L.requestVersion = Y.HttpVersion major minor }
10161012
1017−----------------------------------------------------------------------------
1018−-- Response
1019−
1020−-- $response
1021−--
1022−-- This section is divided into three sub-sections. The first one describes
1023−-- options for response interpretation that are available to you
1024−-- out-of-the-box. The second section called “Inspecting a response” lists a
1025−-- set of functions that can be used to extract useful info from a response
1026−-- returned by 'req'. Finally the third section talks about 'HttpResponse'
1027−-- type class that allows user to add new interpretations of HTTP responses.
1028−
10291013----------------------------------------------------------------------------
10301014-- Response interpretations
10311015
@@ -1181,14 +1165,28 @@ responseRequest (ReturnRequest request) = request
11811165----------------------------------------------------------------------------
11821166-- Response — defining your own interpretation
11831167
1184−-- | Here we need to provide various options how to consume responses.
1168+-- $new-response-interpretation
1169+--
1170+-- To create a new response interpretation you just need to make your data
1171+-- type an instance of 'HttpResponse' type class.
1172+
1173+-- | A type class for response interpretations. It allows to fully control
1174+-- how request is made and how its body is parsed.
11851175
11861176class HttpResponse response where
11871177
1178+ -- | The associated type is type of body that can be extracted from a
1179+ -- instance of 'HttpResponse'.
1180+
11881181 type HttpResponseBody response :: *
11891182
1183+ -- | The method describes how to get underlying 'L.Response' record.
1184+
11901185 toVanillaResponse :: response -> L.Response (HttpResponseBody response)
11911186
1187+ -- | This method describes how to make an HTTP request given 'L.Request'
1188+ -- (prepared by the rest of the library) and 'L.Manager'.
1189+
11921190 getHttpResponse :: L.Request -> L.Manager -> IO response
11931191
11941192----------------------------------------------------------------------------