@@ -33,15 +33,14 @@
33-- but it requires a bit more typing.
33-- but it requires a bit more typing.
35-- “Type-safe” means that the library is protective and eliminates certain
35-- “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
36+-- class of errors. For example, we have correct-by-construction 'Url's,
38−-- 'Url's, it's guaranteed that user does not send request body when using
37+-- it's guaranteed that user does not send request body when using methods
39−-- methods like 'GET' or 'OPTIONS', amount of implicit assumptions is
38+-- like 'GET' or 'OPTIONS', amount of implicit assumptions is minimized by
40−-- minimized by making user specify his\/her intentions in explicit form
39+-- making user specify his\/her intentions in explicit form (for example,
41−-- (for example, it's not possible to avoid specifying body or method of a
40+-- it's not possible to avoid specifying body or method of a request).
42−-- request). Authentication methods that assume TLS force user to use TLS on
41+-- Authentication methods that assume TLS force user to use TLS on type
43−-- type level. The library carefully hides underlying types from lower-level
42+-- level. The library carefully hides underlying types from lower-level
44−-- @http-client@ package because it's not type safe enough (for example
43+-- @http-client@ package because it's not safe enough (for example
45-- 'L.Request' is an instance of 'Data.String.IsString' and if it's
44-- 'L.Request' is an instance of 'Data.String.IsString' and if it's
46-- malformed, it will blow up at run-time).
45-- malformed, it will blow up at run-time).
@@ -169,7 +168,6 @@ module Network.HTTP.Req
169 , responseTimeout
168 , responseTimeout
170 , httpVersion
169 , httpVersion
171 -- * Response
170 -- * Response
173 -- ** Response interpretations
171 -- ** Response interpretations
174 , IgnoreResponse
172 , IgnoreResponse
175 , ignoreResponse
173 , ignoreResponse
@@ -189,6 +187,7 @@ module Network.HTTP.Req
189 , responseCookieJar
187 , responseCookieJar
190 , responseRequest
188 , responseRequest
191 -- ** Defining your own interpretation
189 -- ** Defining your own interpretation
190+ -- $new-response-interpretation
192 , HttpResponse (..)
191 , HttpResponse (..)
193 -- * Other
192 -- * Other
194 , HttpException (..)
193 , HttpException (..)
@@ -759,8 +758,6 @@ instance HttpBody body => RequestComponent (Womb "body" body) where
759-- optional parameters like query parameters and headers. See sections below
758-- optional parameters like query parameters and headers. See sections below
760-- to learn which 'Option' primitives are available.
759-- to learn which 'Option' primitives are available.
762−-- TODO We need examples here.
764data Option (scheme :: Scheme) =
761data Option (scheme :: Scheme) =
765 Option (Endo (Y.QueryText, L.Request)) (Maybe (Endo L.Request))
762 Option (Endo (Y.QueryText, L.Request)) (Maybe (Endo L.Request))
766 -- NOTE 'QueryText' is just [(Text, Maybe Text)], we keep it along with
763 -- NOTE 'QueryText' is just [(Text, Maybe Text)], we keep it along with
@@ -880,7 +877,7 @@ attachHeader name value x =
881-- Support for cookies is quite minimalistic at the moment, its' possible to
878-- Support for cookies is quite minimalistic at the moment, its' possible to
882-- specify which cookies to send using 'cookieJar' and inspect 'L.Response'
879-- 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').
885-- | Use the given 'L.CookieJar'. A 'L.CookieJar' can be obtained from a
882-- | Use the given 'L.CookieJar'. A 'L.CookieJar' can be obtained from a
886-- 'L.Response' record.
883-- 'L.Response' record.
@@ -901,9 +898,20 @@ cookieJar jar = withRequest $ \x ->
901-- additional type safety that prevents leaking of credentials in cases when
898-- additional type safety that prevents leaking of credentials in cases when
902-- authentication relies on TLS for encrypting sensitive data.
899-- authentication relies on TLS for encrypting sensitive data.
901+-- | The 'Option' adds basic authentication.
903+-- See also: <https://en.wikipedia.org/wiki/Basic_access_authentication>.
906+ :: ByteString -- ^ Username
907+ -> ByteString -- ^ Password
908+ -> Option 'Https -- ^ Auth 'Option'
909+basicAuth username password = asFinalizer
910+ (L.applyBasicAuth username password)
904-- | OAuth 1 authentication 'Option'.
912-- | OAuth 1 authentication 'Option'.
906−-- See also: <https://en.wikipedia.org/wiki/OAuth>
914+-- See also: <https://en.wikipedia.org/wiki/OAuth>.
909 :: ByteString -- ^ Consumer token
917 :: ByteString -- ^ Consumer token
@@ -914,18 +922,6 @@ oAuth1
914oAuth1 ctoken csecret otoken osecret = asFinalizer
922oAuth1 ctoken csecret otoken osecret = asFinalizer
915 (OAuth1.signRequest ctoken csecret otoken osecret)
923 (OAuth1.signRequest ctoken csecret otoken osecret)
917−-- | The 'Option' adds basic authentication. The 'Text' values will be UTF-8
920−-- See also: <https://en.wikipedia.org/wiki/Basic_access_authentication>
923− :: ByteString -- ^ Username
924− -> ByteString -- ^ Password
925− -> Option 'Https -- ^ Auth 'Option'
926−basicAuth username password = asFinalizer
927− (L.applyBasicAuth username password)
929-- | The 'Option' adds an OAuth2 bearer token. This is treated by many
925-- | The 'Option' adds an OAuth2 bearer token. This is treated by many
930-- services as the equivalent of a username and password.
926-- services as the equivalent of a username and password.
@@ -933,7 +929,7 @@ basicAuth username password = asFinalizer
934-- > oAuth2Bearer token = header "Authorization" ("Bearer " <> token)
930-- > oAuth2Bearer token = header "Authorization" ("Bearer " <> token)
936−-- See also: <https://en.wikipedia.org/wiki/OAuth>
932+-- See also: <https://en.wikipedia.org/wiki/OAuth>.
938oAuth2Bearer
934oAuth2Bearer
939 :: ByteString -- ^ Token
935 :: ByteString -- ^ Token
@@ -949,7 +945,7 @@ oAuth2Bearer token = asFinalizer
950-- > oAuth2Token token = header "Authorization" ("token" <> token)
946-- > oAuth2Token token = header "Authorization" ("token" <> token)
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>.
954oAuth2Token
950oAuth2Token
955 :: ByteString -- ^ Token
951 :: ByteString -- ^ Token
@@ -959,7 +955,7 @@ oAuth2Token token = asFinalizer
960-- | The 'Option' adds AWS v4 request signature.
956-- | The 'Option' adds AWS v4 request signature.
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>.
965 :: ByteString -- ^ AWS access key
961 :: ByteString -- ^ AWS access key
@@ -1014,18 +1010,6 @@ httpVersion
1014httpVersion major minor = withRequest $ \x ->
1010httpVersion major minor = withRequest $ \x ->
1015 x { L.requestVersion = Y.HttpVersion major minor }
1011 x { L.requestVersion = Y.HttpVersion major minor }
1017−----------------------------------------------------------------------------
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.
1029----------------------------------------------------------------------------
1013----------------------------------------------------------------------------
1030-- Response interpretations
1014-- Response interpretations
@@ -1181,14 +1165,28 @@ responseRequest (ReturnRequest request) = request
1181----------------------------------------------------------------------------
1165----------------------------------------------------------------------------
1182-- Response — defining your own interpretation
1166-- Response — defining your own interpretation
1184−-- | Here we need to provide various options how to consume responses.
1168+-- $new-response-interpretation
1170+-- To create a new response interpretation you just need to make your data
1171+-- type an instance of 'HttpResponse' type class.
1173+-- | A type class for response interpretations. It allows to fully control
1174+-- how request is made and how its body is parsed.
1186class HttpResponse response where
1176class HttpResponse response where
1178+ -- | The associated type is type of body that can be extracted from a
1179+ -- instance of 'HttpResponse'.
1188 type HttpResponseBody response :: *
1181 type HttpResponseBody response :: *
1183+ -- | The method describes how to get underlying 'L.Response' record.
1190 toVanillaResponse :: response -> L.Response (HttpResponseBody response)
1185 toVanillaResponse :: response -> L.Response (HttpResponseBody response)
1187+ -- | This method describes how to make an HTTP request given 'L.Request'
1188+ -- (prepared by the rest of the library) and 'L.Manager'.
1192 getHttpResponse :: L.Request -> L.Manager -> IO response
1190 getHttpResponse :: L.Request -> L.Manager -> IO response
1194----------------------------------------------------------------------------
1192----------------------------------------------------------------------------