@@ -17,10 +17,22 @@ import Servant.Common.Req
17import Servant.Docs
17import Servant.Docs
18import Servant.Server
18import Servant.Server
20−-- | Endpoint for PUT requests.
20+-- | Endpoint for PUT requests. The type @a@ is the type of the
21+-- response body that's returned.
22 deriving Typeable
23 deriving Typeable
25+-- | When implementing the handler for a 'Put' endpoint,
26+-- just like for 'Servant.API.Delete.Delete', 'Servant.API.Get.Get'
27+-- and 'Servant.API.Post.Post', the handler code runs in the
28+-- @EitherT (Int, String) IO@ monad, where the 'Int' represents
29+-- the status code and the 'String' a message, returned in case of
30+-- failure. You can quite handily use 'Control.Monad.Trans.EitherT.left'
31+-- to quickly fail if some conditions are not met.
33+-- If successfully returning a value, we just require that its type has
34+-- a 'ToJSON' instance and servant takes care of encoding it for you,
35+-- yielding status code 200 along the way.
24instance ToJSON a => HasServer (Put a) where
36instance ToJSON a => HasServer (Put a) where
25 type Server (Put a) = EitherT (Int, String) IO a
37 type Server (Put a) = EitherT (Int, String) IO a
@@ -37,6 +49,10 @@ instance ToJSON a => HasServer (Put a) where
38 | otherwise = respond $ failWith NotFound
50 | otherwise = respond $ failWith NotFound
52+-- | If you have a 'Put' endpoint in your API, the client
53+-- side querying function that is created when calling 'client'
54+-- will just require an argument that specifies the scheme, host
55+-- and port to send the request to.
40instance FromJSON a => HasClient (Put a) where
56instance FromJSON a => HasClient (Put a) where
41 type Client (Put a) = BaseUrl -> EitherT String IO a
57 type Client (Put a) = BaseUrl -> EitherT String IO a