@@ -130,12 +130,12 @@ module Network.HTTP.Req
130130 -- ** Body
131131 -- $body
132132 , NoReqBody (..)
133+ , ReqBodyJSON (..)
134+ , ReqBodyFile (..)
133135 , ReqBodyBs (..)
134136 , ReqBodyLbs (..)
135137 , ReqBodyUrlEnc (..)
136138 , FormUrlEncodedParam
137− , ReqBodyMultipart (..)
138− , ReqBodyJSON (..)
139139 , HttpBody (..)
140140 , ProvidesBody
141141 -- ** Optional parameters
@@ -588,6 +588,31 @@ data NoReqBody = NoReqBody
588588instance HttpBody NoReqBody where
589589 getRequestBody NoReqBody = L.RequestBodyBS B.empty
590590
591+-- | This body option allows to use a JSON object as request body — probably
592+-- the most popular format right now. Just wrap a data type that is an
593+-- instance of 'ToJSON' type class and you are done: it will be converted to
594+-- JSON and inserted as request body.
595+--
596+-- This body option sets the @Content-Type@ header to @\"application/json;
597+-- charset=utf-8\"@ value.
598+
599+newtype ReqBodyJSON a = ReqBodyJSON a
600+
601+instance ToJSON a => HttpBody (ReqBodyJSON a) where
602+ getRequestBody (ReqBodyJSON a) = L.RequestBodyLBS (A.encode a)
603+ getRequestContentType Proxy = pure "application/json; charset=utf-8"
604+
605+-- | This body option streams request body from a file. It is expected that
606+-- the file size does not change during the streaming.
607+--
608+-- Using of this body option does not set the @Content-Type@ header.
609+
610+newtype ReqBodyFile = ReqBodyFile FilePath
611+
612+instance HttpBody ReqBodyFile where
613+ getRequestBody (ReqBodyFile path) =
614+ LI.RequestBodyIO (L.streamFile path)
615+
591616-- | HTTP request body represented by a strict 'ByteString'.
592617--
593618-- Using of this body option does not set the @Content-Type@ header.
@@ -621,7 +646,7 @@ instance HttpBody ReqBodyLbs where
621646-- > queryFlag "baz"
622647--
623648-- This body option sets the @Content-Type@ header to
624−-- @application/x-www-from-urlencoded@ value.
649+-- @\"application/x-www-from-urlencoded\"@ value.
625650
626651newtype ReqBodyUrlEnc = ReqBodyUrlEnc FormUrlEncodedParam
627652
@@ -640,21 +665,28 @@ newtype FormUrlEncodedParam = FormUrlEncodedParam [(Text, Maybe Text)]
640665instance QueryParam FormUrlEncodedParam where
641666 queryParam name mvalue = FormUrlEncodedParam [(name, mvalue)]
642667
643−-- |
668+-- | A type class for things that can be interpreted as HTTP
669+-- 'L.RequestBody'.
644670
645−newtype ReqBodyMultipart = ReqBodyMultipart ByteString
671+class HttpBody body where
646672
647−newtype ReqBodyJSON a = ReqBodyJSON a
673+ {-# MINIMAL getRequestBody #-}
648674
649−instance ToJSON a => HttpBody (ReqBodyJSON a) where
650− getRequestBody (ReqBodyJSON a) = L.RequestBodyLBS (A.encode a)
651− getRequestContentType Proxy = pure "application/json; charset=utf-8"
675+ -- | How to get actual 'L.RequestBody'.
652676
653−class HttpBody body where
654677 getRequestBody :: body -> L.RequestBody
678+
679+ -- | This method allows to optionally specify value of @Content-Type@
680+ -- header that should be used when this body option is used. By default
681+ -- this returns 'Nothing' and so @Content-Type@ is not set.
682+
655683 getRequestContentType :: Proxy body -> Maybe ByteString
656684 getRequestContentType Proxy = Nothing
657685
686+-- | The type function recognizes 'NoReqBody' as having 'NoBody', while any
687+-- other body option 'CanHaveBody'. This forces user to use 'NoReqBody' with
688+-- 'GET' method and other methods that do not assume any body.
689+
658690type family ProvidesBody body :: CanHaveBody where
659691 ProvidesBody NoReqBody = 'NoBody
660692 ProvidesBody body = 'CanHaveBody