Network.HTTP.Client.Request.Modifiers

Each of the functions in this module is a monadic request modifier, using the ReqMod type. Most of them do not have any side effects; however, the consistent use of Monad allows for easy chaining with bind (>>=) or Kleisli composition (>=>).

Example

The example that inspired this package is modifying the Request from parseUrl:

  parseUrl "http://httpbin.org/post"
    >>= setMethod POST
    >>= setBodyLBS "hello"

Suppose I want to reuse the URL post request but not the body. I can define a function for just that part:

  let httpbinPost :: MonadThrow m => m Request
      httpbinPost = parseUrl "http://httpbin.org/post" >>= setMethod POST

Alternative formulations of the above, without using request modifiers, are:

  parseUrl "http://httpbin.org/post"
    >>= req -> return $ req
      { method = renderStdMethod POST
      , requestBody = RequestBodyLBS "hello"
      }

and

  let httpbinPost :: MonadThrow m => m Request
      httpbinPost = do req <- parseUrl "http://httpbin.org/post"
                       return $ req { method = renderStdMethod POST }

Benefits

The main benefits of monadic request modifiers are:

• composability,
• conciseness, and
• allowing an arbitrary combination of Monads.

Naming Scheme

The naming scheme used for functions in this module is:

• set - Set a value, overriding any existing value.
• add - Append a value to the end of a list and do not override any existing values.
• BS - Use a strict ByteString as a parameter.
• LBS - Use a lazy ByteString as a parameter.

Request Modifier Type

type ReqMod m = Request -> m Request

Request modifier, abbreviated

Since 0.1

URI/URL

setUri :: MonadThrow m => URI -> ReqMod m

Validate and set the request URI.

Since 0.1

setUriRelative :: MonadThrow m => URI -> ReqMod m

Extend the request URI with a relative URI.

Since 0.1

Query String

setQueryBS :: Monad m => ByteString -> ReqMod m

Set the query string with a strict ByteString.

Since 0.1

setQuery :: (Monad m, QueryLike q) => q -> ReqMod m

Set the query string with a rendered Query.

Since 0.1

addQuery :: (Monad m, QueryLike q) => q -> ReqMod m

Add a rendered Query to the end of the query string.

Since 0.1

addQueryPair :: (Monad m, QueryKeyLike k, QueryValueLike v) => k -> v -> ReqMod m

Add a single query key/value pair to the end of the query string.

Since 0.1

Method

setMethodBS :: Monad m => Method -> ReqMod m

Set the method with a strict ByteString.

See Network.HTTP.Types.Method for the methods, e.g. methodGet or methodPost.

Since 0.1

setMethod :: Monad m => StdMethod -> ReqMod m

Set the method with a standard method, e.g. GET or POST.

Since 0.1

Headers

setHeaders :: Monad m => RequestHeaders -> ReqMod m

Set the request headers.

Since 0.1

setHeader :: Monad m => HeaderName -> ByteString -> ReqMod m

Set the request header by name, removing any other headers with the same name.

Since 0.1

addHeaders :: Monad m => RequestHeaders -> ReqMod m

Add headers to the request.

Since 0.1

addHeader :: Monad m => HeaderName -> ByteString -> ReqMod m

Add a single header.

Since 0.1

setContentTypeHeader :: Monad m => MediaType -> ReqMod m

Set the Content-Type header with a MediaType.

Since 0.1

setAcceptHeader :: Monad m => MediaType -> ReqMod m

Set the Accept header with a MediaType.

Since 0.1

Body

setBody :: Monad m => RequestBody -> Request -> m Request

Set the request body.

Since 0.1

setBodyBS :: Monad m => ByteString -> Request -> m Request

Set the request body with a strict ByteString.

Since 0.1

setBodyLBS :: Monad m => ByteString -> Request -> m Request

Set the request body with a lazy ByteString.

Since 0.1

setUrlEncodedBody :: Monad m => [(ByteString, ByteString)] -> ReqMod m

Set the request body with URL-encoded key/value pairs.

Since 0.1

Convenient Combinations

setSimpleRequestBS :: Monad m => StdMethod -> MediaType -> ByteString -> ReqMod m

Set the method, Content-Type, and strict ByteString body.

Since 0.1

setSimpleRequestLBS :: Monad m => StdMethod -> MediaType -> ByteString -> ReqMod m

Set the method, Content-Type, and lazy ByteString body.

Since 0.1