@@ -23,6 +23,17 @@ import Servant.Server
2323data Post a
2424 deriving Typeable
2525
26+-- | When implementing the handler for a 'Post' endpoint,
27+-- just like for 'Servant.API.Delete.Delete', 'Servant.API.Get.Get'
28+-- and 'Servant.API.Put.Put', the handler code runs in the
29+-- @EitherT (Int, String) IO@ monad, where the 'Int' represents
30+-- the status code and the 'String' a message, returned in case of
31+-- failure. You can quite handily use 'Control.Monad.Trans.EitherT.left'
32+-- to quickly fail if some conditions are not met.
33+--
34+-- If successfully returning a value, we just require that its type has
35+-- a 'ToJSON' instance and servant takes care of encoding it for you,
36+-- yielding status code 201 along the way.
2637instance ToJSON a => HasServer (Post a) where
2738 type Server (Post a) = EitherT (Int, String) IO a
2839
@@ -38,6 +49,10 @@ instance ToJSON a => HasServer (Post a) where
3849 respond $ failWith WrongMethod
3950 | otherwise = respond $ failWith NotFound
4051
52+-- | If you have a 'Post' 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.
4156instance FromJSON a => HasClient (Post a) where
4257 type Client (Post a) = BaseUrl -> EitherT String IO a
4358