diff --git a/Network/HTTP/Client.hs b/Network/HTTP/Client.hs --- a/Network/HTTP/Client.hs +++ b/Network/HTTP/Client.hs @@ -10,57 +10,57 @@ -- http-client-tls provide secure connections. -- -- There are three core components to be understood here: requests, responses, --- and managers. A @Manager@ keeps track of open connections to various hosts, +-- and managers. A 'Manager' keeps track of open connections to various hosts, -- and when requested, will provide either an existing open connection or --- create a new connection on demand. A @Manager@ also automatically reaps --- connections which have been unused for a certain period of time. A @Manager@ +-- create a new connection on demand. A 'Manager' also automatically reaps +-- connections which have been unused for a certain period of time. A 'Manager' -- allows for more efficient HTTP usage by allowing for keep-alive connections. -- Secure HTTP connections can be allowed by modifying the settings used for --- creating a manager. The simplest way to create a @Manager@ is with: +-- creating a manager. The simplest way to create a 'Manager' is with: -- -- @ -- 'newManager' 'defaultManagerSettings' -- @ -- --- While generally speaking it is a good idea to share a single @Manager@ +-- While generally speaking it is a good idea to share a single 'Manager' -- throughout your application, there are cases where it makes more sense to --- create and destroy @Manager@s more frequently. As an example, if you have an +-- create and destroy 'Manager's more frequently. As an example, if you have an -- application which will make a large number of requests to different hosts, -- and will never make more than one connection to a single host, then sharing --- a @Manager@ will result in idle connections being kept open longer than --- necessary. In such a situation, it makes sense to use @withManager@ around +-- a 'Manager' will result in idle connections being kept open longer than +-- necessary. In such a situation, it makes sense to use 'withManager' around -- each new request, to avoid running out of file descriptors. (Note that the -- 'managerIdleConnectionCount' setting mitigates the risk of leaking too many -- file descriptors.) -- --- The next core component is a @Request@, which represents a single HTTP --- request to be sent to a specific server. @Request@s allow for many settings +-- The next core component is a 'Request', which represents a single HTTP +-- request to be sent to a specific server. 'Request's allow for many settings -- to control exact how they function, but usually the simplest approach for --- creating a @Request@ is to use 'parseUrl'. +-- creating a 'Request' is to use 'parseUrl'. -- --- Finally, a @Response@ is the result of sending a single @Request@ to a --- server, over a connection which was acquired from a @Manager@. Note that you +-- Finally, a 'Response' is the result of sending a single 'Request' to a +-- server, over a connection which was acquired from a 'Manager'. Note that you -- must close the response when you're done with it to ensure that the --- connection is recycled to the @Manager@ to either be used by another --- request, or to be reaped. Usage of @withResponse@ will ensure that this +-- connection is recycled to the 'Manager' to either be used by another +-- request, or to be reaped. Usage of 'withResponse' will ensure that this -- happens automatically. -- -- Helper packages may provide replacements for various recommendations listed -- above. For example, if using http-client-tls, instead of using --- 'defaultManagerSettings', you would want to use @tlsManagerSettings@. Be +-- 'defaultManagerSettings', you would want to use 'tlsManagerSettings'. Be -- sure to read the relevant helper library documentation for more information. -- -- A note on exceptions: for the most part, all actions that perform I/O should --- be assumed to throw an @HttpException@ in the event of some problem, and all --- pure functions will be total. For example, @withResponse@, @httpLbs@, and --- @BodyReader@ can all throw exceptions. Functions like @responseStatus@ and --- @applyBasicAuth@ are guaranteed to be total (or there\'s a bug in the +-- be assumed to throw an 'HttpException' in the event of some problem, and all +-- pure functions will be total. For example, 'withResponse', 'httpLbs', and +-- 'BodyReader' can all throw exceptions. Functions like 'responseStatus' and +-- 'applyBasicAuth' are guaranteed to be total (or there\'s a bug in the -- library). -- --- One thing to be cautioned about: the type of @parseUrl@ allows it to work in --- different monads. If used in the @IO@ monad, it will throw an exception in +-- One thing to be cautioned about: the type of 'parseUrl' allows it to work in +-- different monads. If used in the 'IO' monad, it will throw an exception in -- the case of an invalid URI. In addition, if you leverage the @IsString@ --- instance of the @Request@ value via @OverloadedStrings@, an invalid URI will +-- instance of the 'Request' value via @OverloadedStrings@, an invalid URI will -- result in a partial value. Caveat emptor! -- -- Non-2xx responses: the default behavior of all functions in http-client is @@ -69,7 +69,9 @@ -- are not in the 2xx range. These behaviors can be overridden by the -- 'redirectCount' and 'checkStatus' settings on a request, respectively. module Network.HTTP.Client - ( -- * Performing requests + ( -- $example1 + + -- * Performing requests withResponse , httpLbs , httpNoBody @@ -265,3 +267,45 @@ -- Since 0.4.7 managerSetProxy :: ProxyOverride -> ManagerSettings -> ManagerSettings managerSetProxy po = managerSetInsecureProxy po . managerSetSecureProxy po + + + +-- $example1 +-- = Example Usage +-- +-- === Making a GET request +-- +-- > import Network.HTTP.Client +-- > import Network.HTTP.Types.Status (statusCode) +-- > +-- > main :: IO () +-- > main = do +-- > manager <- newManager defaultManagerSettings +-- > +-- > request <- parseUrl "http://httpbin.org/post" +-- > response <- httpLbs request manager +-- > +-- > putStrLn $ "The status code was: " ++ (show $ statusCode $ responseStatus response) +-- > print $ responseBody response +-- +-- +-- === Posting JSON to a server +-- +-- > {-# LANGUAGE OverloadedStrings #-} +-- > import Network.HTTP.Client +-- > import Network.HTTP.Types.Status (statusCode) +-- > import Data.Aeson (object, (.=), encode) +-- > +-- > main :: IO () +-- > main = do +-- > manager <- newManager defaultManagerSettings +-- > +-- > -- Create the request +-- > let requestObject = object ["name" .= "Michael", "age" .= 30] +-- > initialRequest <- parseUrl "http://httpbin.org/post" +-- > let request = initialRequest { method = "POST", requestBody = RequestBodyLBS $ encode requestObject } +-- > +-- > response <- httpLbs request manager +-- > putStrLn $ "The status code was: " ++ (show $ statusCode $ responseStatus response) +-- > print $ responseBody response +-- diff --git a/http-client.cabal b/http-client.cabal --- a/http-client.cabal +++ b/http-client.cabal @@ -1,5 +1,5 @@ name: http-client -version: 0.4.22 +version: 0.4.22.1 synopsis: An HTTP client engine, intended as a base layer for more user-friendly packages. description: Hackage documentation generation is not reliable. For up to date documentation, please see: . homepage: https://github.com/snoyberg/http-client