Type-class for making HTTP requests

Functions of this module require the MonadHttp constraint. This type class allows us to instantiate differently in different contexts, most usefully with stubbed responses in test. (See Freckle.App.Test.Http.)

The IO instance does what you would expect, and can be used to either build your own instances:

instance MonadIO m => MonadHttp (AppT m) where
  httpLbs = liftIO . httpLbs

instance MonadHttp (HandlerFor App) where
  httpLbs = liftIO . httpLbs

Or directly,

resp <- liftIO $ httpLbs ...

Make a request and parse the body as JSON

-- Throws, but only on a complete failure to perform the request
resp <- httpJson $ parseRequest_ "https://example.com"

-- Safe access
getResponseBody resp :: Either HttpDecodeError a

-- Unsafe access (throws on Left)
getResponseBodyUnsafe resp :: m a

Make a request and decode the body using the given function

This be used to request other formats, e.g. CSV.

Request all pages of a paginated endpoint into some Monoid

For example,

Interact with a paginated endpoint where each page is a JSON list, combining all the pages into one list (i.e. concat) and throw on any decoding errors:

httpPaginated httpJson getResponseBodyUnsafe $ parseRequest_ "https://..."

This uses sourcePaginated, and so reads a Link header. To do otherwise, drop down to sourcePaginatedBy directly.

The second argument is used to extract the data to combine out of the response. This is particularly useful for Either values, like you may get from httpJson. It lives in m to support functions such as getResponseBodyUnsafe.

Decoding errors can be handled differently by adjusting what Monoid you convert each page's response into:

httpPaginated httpJson fromResponseLenient $ parseRequest_ "https://..."

fromResponseLenient
  :: MonadLogger m
  => Response (Either e [MyJsonThing])
  -> m [MyJsonThing]
fromResponseLenient r = case getResponseBody r of
     Left _ -> [] <$ logWarn "..."
     Right a -> pure a

See Freckle.Http.App.Paginate to process requested pages in a streaming fashion, or perform pagination based on somethign other than Link.

Stream pages of a paginated response, using Link to find next pages

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

Convert a URL into a Request.

This function 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.:

parseRequest "POST http://httpbin.org/post"

Note that the request method must be provided as all capital letters.

A Request created by this function won't cause exceptions on non-2XX response status codes.

To create a request which throws on non-2XX status codes, see parseUrlThrow

Since: http-client-0.4.30

Same as parseRequest, but parse errors cause an impure exception. Mostly useful for static strings which are known to be correctly formatted.

Add a request header name/value combination

Since: http-conduit-2.1.10

Add to the existing query string parameters.

Since: http-conduit-2.3.5

Set basic auth with the given username and password

Since: http-conduit-2.1.10

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; charset=utf-8

NOTE: Depends on the aeson cabal flag being enabled

Since: http-conduit-2.1.10

Set the request body as URL encoded data

Note: This will change the request method to POST and set the content-type to application/x-www-form-urlencoded

Since: http-conduit-2.1.10

Modify the request so that non-2XX status codes generate a runtime StatusCodeException, by using throwErrorStatusCodes

Since: http-client-0.5.13

Lens for the requested path info of the request

Since: http-conduit-2.1.10

A simple representation of the HTTP response.

Since 0.1.0

Get the status of the response

Since: http-conduit-2.1.10

Get the response body

Since: http-conduit-2.1.10

Read an Either response body, throwing any Left as an exception

If you plan to use this function, and haven't built your decoding to handle error response bodies too, you'll want to use setRequestCheckStatus so that you see status-code exceptions before HttpDecodeErrors.

An exception which may be generated by this library

Since: http-client-0.5.0

HTTP Status.

Only the statusCode is used for comparisons.

Please use mkStatus to create status codes from code and message, or the Enum instance or the status code constants (like ok200). There might be additional record members in the future.

Note that the Show instance is only for debugging.

Informational class

Checks if the status is in the 1XX range.

Since: http-types-0.8.0

Successful class

Checks if the status is in the 2XX range.

Since: http-types-0.8.0

Redirection class

Checks if the status is in the 3XX range.

Since: http-types-0.8.0

Client Error class

Checks if the status is in the 4XX range.

Since: http-types-0.8.0

Server Error class

Checks if the status is in the 5XX range.

Since: http-types-0.8.0