doc/tutorial/Client.lhs · servant

git.iko.soy/servant

on type-errors help sign in

257 lines 9.1 kB history raw

1# Querying an API

3While defining handlers that [serve an API](Server.html) has a lot to it, querying an API is simpler: we do not care about what happens inside the webserver, we just need to know how to talk to it and get a response back. That said, we usually have to write the querying functions by hand because the structure of the API isn't a first class citizen and can't be inspected to generate the client-side functions.

5**servant** however has a way to inspect APIs, because APIs are just Haskell types and (GHC) Haskell lets us do quite a few things with types. In the same way that we look at an API type to deduce the types the handlers should have, we can inspect the structure of the API to *derive* Haskell functions that take one argument for each occurrence of `Capture`, `ReqBody`, `QueryParam`

6and friends (see [the tutorial introduction](ApiType.html) for an overview). By *derive*, we mean that there's no code generation involved - the functions are defined just by the structure of the API type.

8The source for this tutorial section is a literate Haskell file, so first we need to have some language extensions and imports:

10``` haskell

11{-# LANGUAGE DataKinds #-}

12{-# LANGUAGE DeriveGeneric #-}

13{-# LANGUAGE TypeOperators #-}

15module Client where

17import Data.Aeson

18import Data.Proxy

19import GHC.Generics

20import Network.HTTP.Client (newManager, defaultManagerSettings)

21import Servant.API

22import Servant.Client

23import Servant.Types.SourceT (foreach)

25import qualified Servant.Client.Streaming as S

26```

28Also, we need examples for some domain specific data types:

30``` haskell

31data Position = Position

32 { xCoord :: Int

33 , yCoord :: Int

34 } deriving (Show, Generic)

36instance FromJSON Position

38newtype HelloMessage = HelloMessage { msg :: String }

39 deriving (Show, Generic)

41instance FromJSON HelloMessage

43data ClientInfo = ClientInfo

44 { clientName :: String

45 , clientEmail :: String

46 , clientAge :: Int

47 , clientInterestedIn :: [String]

48 } deriving Generic

50instance ToJSON ClientInfo

52data Email = Email

53 { from :: String

54 , to :: String

55 , subject :: String

56 , body :: String

57 } deriving (Show, Generic)

59instance FromJSON Email

60```

62Enough chitchat, let's see an example. Consider the following API type from the previous section:

64``` haskell

65type API = "position" :> Capture "x" Int :> Capture "y" Int :> Get '[JSON] Position

66 :<|> "hello" :> QueryParam "name" String :> Get '[JSON] HelloMessage

67 :<|> "marketing" :> ReqBody '[JSON] ClientInfo :> Post '[JSON] Email

68```

70What we are going to get with **servant-client** here is three functions, one to query each endpoint:

72``` haskell

73position :: Int -- ^ value for "x"

74 -> Int -- ^ value for "y"

75 -> ClientM Position

77hello :: Maybe String -- ^ an optional value for "name"

78 -> ClientM HelloMessage

80marketing :: ClientInfo -- ^ value for the request body

81 -> ClientM Email

82```

84Each function makes available as an argument any value that the response may

85depend on, as evidenced in the API type. How do we get these functions? By calling

86the function `client`. It takes one argument:

88- a `Proxy` to your API,

90``` haskell

91api :: Proxy API

92api = Proxy

94position :<|> hello :<|> marketing = client api

95```

97`client api` returns client functions for our _entire_ API, combined with `:<|>`, which we can pattern match on as above. You could say `client` "calculates" the correct type and number of client functions for the API type it is given (via a `Proxy`), as well as their implementations.

99If you have an `EmptyAPI` in your API, servant-client will hand you a value of

100type `EmptyClient` in the corresponding slot, where `data EmptyClient =

101EmptyClient`, as a way to indicate that you can't do anything useful with it.

102

103``` haskell ignore

104type API' = API :<|> EmptyAPI

105

106api' :: Proxy API'

107api' = Proxy

108

109(position' :<|> hello' :<|> marketing') :<|> EmptyClient = client api'

110```

111

112``` haskell ignore

113-- | URI scheme to use

114data Scheme =

115 Http -- ^ http://

116 | Https -- ^ https://

117 deriving

118

119-- | Simple data type to represent the target of HTTP requests

120-- for servant's automatically-generated clients.

121data BaseUrl = BaseUrl

122 { baseUrlScheme :: Scheme -- ^ URI scheme to use

123 , baseUrlHost :: String -- ^ host (eg "haskell.org")

124 , baseUrlPort :: Int -- ^ port (eg 80)

125 , baseUrlPath :: String -- ^ path (eg "/a/b/c")

126 }

127```

128

129That's it. Let's now write some code that uses our client functions.

130

131``` haskell

132queries :: ClientM (Position, HelloMessage, Email)

133queries = do

134 pos <- position 10 10

135 message <- hello (Just "servant")

136 em <- marketing (ClientInfo "Alp" "alp@foo.com" 26 ["haskell", "mathematics"])

137 return (pos, message, em)

138

139run :: IO ()

140run = do

141 manager' <- newManager defaultManagerSettings

142 res <- runClientM queries (mkClientEnv manager' (BaseUrl Http "localhost" 8081 ""))

143 case res of

144 Left err -> putStrLn $ "Error: " ++ show err

145 Right (pos, message, em) -> do

146 print pos

147 print message

148 print em

149```

150

151Here's the output of the above code running against the appropriate server:

152

153```

154Position {xCoord = 10, yCoord = 10}

155HelloMessage {msg = "Hello, servant"}

156Email {from = "great@company.com", to = "alp@foo.com", subject = "Hey Alp, we miss you!", body = "Hi Alp,\n\nSince you've recently turned 26, have you checked out our latest haskell, mathematics products? Give us a visit!"}

157```

158

159The types of the arguments for the functions are the same as for (server-side) request handlers.

160

161## Changing the monad the client functions live in

162

163Just like `hoistServer` allows us to change the monad in which request handlers

164of a web application live, we also have `hoistClient` for changing the monad

165in which _client functions_ live. Consider the following trivial API:

166

167``` haskell

168type HoistClientAPI = Get '[JSON] Int :<|> Capture "n" Int :> Post '[JSON] Int