| Safe Haskell | None |
|---|---|
| Language | Haskell98 |
Network.HTTP.Simple
Contents
Description
Simplified interface for common HTTP client interactions. Tutorial available at https://github.com/commercialhaskell/jump/blob/master/doc/http-client.md.
Important note: Request is an instance of IsString, and therefore
recommended usage is to turn on OverloadedStrings, e.g.
@@@ {--} import Network.HTTP.Simple import qualified Data.ByteString.Lazy.Char8 as L8
main :: IO () main = httpLBS "http://example.com" >>= L8.putStrLn @@@
- httpLBS :: MonadIO m => Request -> m (Response ByteString)
- httpJSON :: (MonadIO m, FromJSON a) => Request -> m (Response a)
- httpJSONEither :: (MonadIO m, FromJSON a) => Request -> m (Response (Either JSONException a))
- httpSink :: (MonadIO m, MonadMask m) => Request -> (Response () -> Sink ByteString m a) -> m a
- data Request :: *
- data Response body :: * -> *
- data JSONException
- data HttpException :: *
- = StatusCodeException Status ResponseHeaders CookieJar
- | InvalidUrlException String String
- | TooManyRedirects [Response ByteString]
- | UnparseableRedirect (Response ByteString)
- | TooManyRetries
- | HttpParserException String
- | HandshakeFailed
- | OverlongHeaders
- | ResponseTimeout
- | FailedConnectionException String Int
- | FailedConnectionException2 String Int Bool SomeException
- | ExpectedBlankAfter100Continue
- | InvalidStatusLine ByteString
- | InvalidHeader ByteString
- | InternalIOException IOException
- | ProxyConnectException ByteString Int (Either ByteString HttpException)
- | NoResponseDataReceived
- | TlsException SomeException
- | TlsNotSupported
- | ResponseBodyTooShort Word64 Word64
- | InvalidChunkHeaders
- | IncompleteHeaders
- | InvalidDestinationHost ByteString
- | HttpZlibException ZlibException
- | InvalidProxyEnvironmentVariable Text Text
- | ResponseLengthAndChunkingBothUsed
- | TlsExceptionHostPort SomeException ByteString Int
- data Proxy :: * = Proxy {
- proxyHost :: ByteString
- proxyPort :: Int
- defaultRequest :: Request
- parseRequest :: MonadThrow m => String -> m Request
- parseRequest_ :: String -> Request
- setRequestMethod :: ByteString -> Request -> Request
- setRequestSecure :: Bool -> Request -> Request
- setRequestHost :: ByteString -> Request -> Request
- setRequestPort :: Int -> Request -> Request
- setRequestPath :: ByteString -> Request -> Request
- addRequestHeader :: HeaderName -> ByteString -> Request -> Request
- getRequestHeader :: HeaderName -> Request -> [ByteString]
- setRequestHeader :: HeaderName -> [ByteString] -> Request -> Request
- setRequestHeaders :: [(HeaderName, ByteString)] -> Request -> Request
- setRequestQueryString :: [(ByteString, Maybe ByteString)] -> Request -> Request
- getRequestQueryString :: Request -> [(ByteString, Maybe ByteString)]
- setRequestBody :: RequestBody -> Request -> Request
- setRequestBodyJSON :: ToJSON a => a -> Request -> Request
- setRequestBodyLBS :: ByteString -> Request -> Request
- setRequestBodySource :: Int64 -> Source IO ByteString -> Request -> Request
- setRequestBodyFile :: FilePath -> Request -> Request
- setRequestBodyURLEncoded :: [(ByteString, ByteString)] -> Request -> Request
- setRequestIgnoreStatus :: Request -> Request
- setRequestBasicAuth :: ByteString -> ByteString -> Request -> Request
- setRequestManager :: Manager -> Request -> Request
- setRequestProxy :: Maybe Proxy -> Request -> Request
- getResponseStatus :: Response a -> Status
- getResponseStatusCode :: Response a -> Int
- getResponseHeader :: HeaderName -> Response a -> [ByteString]
- getResponseHeaders :: Response a -> [(HeaderName, ByteString)]
- getResponseBody :: Response a -> a
- httpLbs :: MonadIO m => Request -> m (Response ByteString)
Perform requests
httpLBS :: MonadIO m => Request -> m (Response ByteString) #
Perform an HTTP request and return the body as a lazy ByteString. Note
that the entire value will be read into memory at once (no lazy I/O will be
performed).
Since: 2.1.10
httpJSON :: (MonadIO m, FromJSON a) => Request -> m (Response a) #
Perform an HTTP request and parse the body as JSON. In the event of an
JSON parse errors, a JSONException runtime exception will be thrown.
Since: 2.1.10
httpJSONEither :: (MonadIO m, FromJSON a) => Request -> m (Response (Either JSONException a)) #
Perform an HTTP request and parse the body as JSON. In the event of an
JSON parse errors, a Left value will be returned.
Since: 2.1.10
httpSink :: (MonadIO m, MonadMask m) => Request -> (Response () -> Sink ByteString m a) -> m a #
Perform an HTTP request and consume the body with the given Sink
Since: 2.1.10
Types
All information on how to connect to a host and what should be sent in the HTTP request.
If you simply wish to download from a URL, see parseRequest.
The constructor for this data type is not exposed. Instead, you should use
either the defaultRequest value, or parseRequest to
construct from a URL, and then use the records below to make modifications.
This approach allows http-client to add configuration options without
breaking backwards compatibility.
For example, to construct a POST request, you could do something like:
initReq <- parseRequest "http://www.example.com/path"
let req = initReq
{ method = "POST"
}For more information, please see http://www.yesodweb.com/book/settings-types.
Since 0.1.0
data JSONException #
An exception that can occur when parsing JSON
Since: 2.1.10
Constructors
| JSONParseException Request (Response ()) ParseError | |
| JSONConversionException Request (Response Value) String |
Instances
data HttpException :: * #
Constructors
| StatusCodeException Status ResponseHeaders CookieJar | |
| InvalidUrlException String String | |
| TooManyRedirects [Response ByteString] | List of encountered responses containing redirects in reverse chronological order; including last redirect, which triggered the exception and was not followed. |
| UnparseableRedirect (Response ByteString) | Response containing unparseable redirect. |
| TooManyRetries | |
| HttpParserException String | |
| HandshakeFailed | |
| OverlongHeaders | |
| ResponseTimeout | |
| FailedConnectionException String Int | host/port Note that in old versions of http-client and http-conduit, this exception would indicate a failed attempt to create a connection. However, since (at least) http-client 0.4, it indicates a timeout occurred while trying to establish the connection. For more information on this, see: |
| FailedConnectionException2 String Int Bool SomeException | host/port/secure |
| ExpectedBlankAfter100Continue | |
| InvalidStatusLine ByteString | |
| InvalidHeader ByteString | |
| InternalIOException IOException | |
| ProxyConnectException ByteString Int (Either ByteString HttpException) | host/port |
| NoResponseDataReceived | |
| TlsException SomeException | |
| TlsNotSupported | |
| ResponseBodyTooShort Word64 Word64 | Expected size/actual size. Since 1.9.4 |
| InvalidChunkHeaders | Since 1.9.4 |
| IncompleteHeaders | |
| InvalidDestinationHost ByteString | |
| HttpZlibException ZlibException | Since 0.3 |
| InvalidProxyEnvironmentVariable Text Text | Environment name and value Since 0.4.7 |
| ResponseLengthAndChunkingBothUsed | Detect a case where both the Since 0.4.11 this exception isn't thrown anymore. |
| TlsExceptionHostPort SomeException ByteString Int | TLS exception, together with the host and port Since: 0.4.24 |
Instances
Define a HTTP proxy, consisting of a hostname and port number.
Constructors
| Proxy | |
Fields
| |
Request constructions
A default request value
Since: 0.4.30
parseRequest :: MonadThrow m => String -> m Request #
Convert a URL into a Request.
This defaults some of the values in Request, such as setting method to
GET and requestHeaders to [].
Since this function uses MonadThrow, the return monad can be anything that is
an instance of MonadThrow, such as IO or Maybe.
You can place the request method at the beginning of the URL separated by a space, e.g.:
@@
parseRequeset "POST http://httpbin.org/post"
@@
Note that the request method must be provided as all capital letters.
Since: 0.4.30
parseRequest_ :: String -> Request #
Same as parseRequest, but in the cases of a parse error
generates an impure exception. Mostly useful for static strings which
are known to be correctly formatted.
Request lenses
Basics
setRequestMethod :: ByteString -> Request -> Request #
Set the request method
Since: 2.1.10
setRequestSecure :: Bool -> Request -> Request #
Set whether this is a secureHTTPS (True) or insecureHTTP
(False) request
Since: 2.1.10
setRequestHost :: ByteString -> Request -> Request #
Set the destination host of the request
Since: 2.1.10
setRequestPort :: Int -> Request -> Request #
Set the destination port of the request
Since: 2.1.10
setRequestPath :: ByteString -> Request -> Request #
Lens for the requested path info of the request
Since: 2.1.10
addRequestHeader :: HeaderName -> ByteString -> Request -> Request #
Add a request header name/value combination
Since: 2.1.10
getRequestHeader :: HeaderName -> Request -> [ByteString] #
Get all request header values for the given name
Since: 2.1.10
setRequestHeader :: HeaderName -> [ByteString] -> Request -> Request #
Set the given request header to the given list of values. Removes any previously set header values with the same name.
Since: 2.1.10
setRequestHeaders :: [(HeaderName, ByteString)] -> Request -> Request #
Set the request headers, wiping out any previously set headers
Since: 2.1.10
setRequestQueryString :: [(ByteString, Maybe ByteString)] -> Request -> Request #
Set the query string parameters
Since: 2.1.10
getRequestQueryString :: Request -> [(ByteString, Maybe ByteString)] #
Get the query string parameters
Since: 2.1.10
Request body
setRequestBody :: RequestBody -> Request -> Request #
Set the request body to the given RequestBody. You may want to
consider using one of the convenience functions in the modules, e.g.
requestBodyJSON.
Note: This will not modify the request method. For that, please use
requestMethod. You likely don't want the default of GET.
Since: 2.1.10
setRequestBodyJSON :: ToJSON a => a -> Request -> Request #
Set the request body as a JSON value
Note: This will not modify the request method. For that, please use
requestMethod. You likely don't want the default of GET.
This also sets the content-type to application/json; chatset=utf8
Since: 2.1.10
setRequestBodyLBS :: ByteString -> Request -> Request #
Set the request body as a lazy ByteString
Note: This will not modify the request method. For that, please use
requestMethod. You likely don't want the default of GET.
Since: 2.1.10
Set the request body as a Source
Note: This will not modify the request method. For that, please use
requestMethod. You likely don't want the default of GET.
Since: 2.1.10
setRequestBodyFile :: FilePath -> Request -> Request #
Set the request body as a file
Note: This will not modify the request method. For that, please use
requestMethod. You likely don't want the default of GET.
Since: 2.1.10
setRequestBodyURLEncoded :: [(ByteString, ByteString)] -> Request -> Request #
Set the request body as URL encoded data
Note: This will not modify the request method. For that, please use
requestMethod. You likely don't want the default of GET.
This also sets the content-type to application/x-www-form-urlencoded
Since: 2.1.10
Special fields
setRequestIgnoreStatus :: Request -> Request #
Modify the request so that non-2XX status codes do not generate a runtime exception.
Since: 2.1.10
Arguments
| :: ByteString | username |
| -> ByteString | password |
| -> Request | |
| -> Request |
Set basic auth with the given username and password
Since: 2.1.10
setRequestManager :: Manager -> Request -> Request #
Instead of using the default global Manager, use the supplied
Manager.
Since: 2.1.10
setRequestProxy :: Maybe Proxy -> Request -> Request #
Override the default proxy server settings
Since: 2.1.10
Response lenses
getResponseStatus :: Response a -> Status #
Get the status of the response
Since: 2.1.10
getResponseStatusCode :: Response a -> Int #
Get the integral status code of the response
Since: 2.1.10
getResponseHeader :: HeaderName -> Response a -> [ByteString] #
Get all response header values with the given name
Since: 2.1.10
getResponseHeaders :: Response a -> [(HeaderName, ByteString)] #
Get all response headers
Since: 2.1.10
getResponseBody :: Response a -> a #
Get the response body
Since: 2.1.10