doc/tutorial/Server.lhs · typeable/servant

git.iko.soy/typeable/servant

on servant-auth-uverb help sign in

typeable/servant/doc/tutorial/Server.lhs

1200 lines 40 kB history raw

1# Serving an API

3Enough chit-chat about type-level combinators and representing an API as a

4type. Can we have a webservice already?

6## A first example

8Equipped with some basic knowledge about the way we represent APIs, let's now

9write our first webservice.

11The source for this tutorial section is a literate haskell file, so first we

12need to have some language extensions and imports:

14``` haskell

15{-# LANGUAGE DataKinds #-}

16{-# LANGUAGE DeriveGeneric #-}

17{-# LANGUAGE FlexibleInstances #-}

18{-# LANGUAGE GeneralizedNewtypeDeriving #-}

19{-# LANGUAGE MultiParamTypeClasses #-}

20{-# LANGUAGE OverloadedStrings #-}

21{-# LANGUAGE RankNTypes #-}

22{-# LANGUAGE ScopedTypeVariables #-}

23{-# LANGUAGE TypeOperators #-}

25module Server where

27import Prelude ()

28import Prelude.Compat

30import Control.Monad.Except

31import Control.Monad.Reader

32import Data.Aeson

33import Data.Aeson.Types

34import Data.Attoparsec.ByteString

35import Data.ByteString (ByteString)

36import Data.List

37import Data.Maybe

38import Data.String.Conversions

39import Data.Time.Calendar

40import GHC.Generics

41import Lucid

42import Network.HTTP.Media ((//), (/:))

43import Network.Wai

44import Network.Wai.Handler.Warp

45import Servant

46import System.Directory

47import Text.Blaze

48import Text.Blaze.Html.Renderer.Utf8

49import Servant.Types.SourceT (source)

50import qualified Data.Aeson.Parser

51import qualified Text.Blaze.Html

52```

54**Important**: the `Servant` module comes from the **servant-server** package,

55the one that lets us run webservers that implement a particular API type. It

56reexports all the types from the **servant** package that let you declare API

57types as well as everything you need to turn your request handlers into a

58fully-fledged webserver. This means that in your applications, you can just add

59**servant-server** as a dependency, import `Servant` and not worry about anything

60else.

62We will write a server that will serve the following API.

64``` haskell

65type UserAPI1 = "users" :> Get '[JSON] [User]

66```

68Here's what we would like to see when making a GET request to `/users`.

70``` javascript

71[ {"name": "Isaac Newton", "age": 372, "email": "isaac@newton.co.uk", "registration_date": "1683-03-01"}

72, {"name": "Albert Einstein", "age": 136, "email": "ae@mc2.org", "registration_date": "1905-12-01"}

73]

74```

76Now let's define our `User` data type and write some instances for it.

78``` haskell

79data User = User

80 { name :: String

81 , age :: Int

82 , email :: String

83 , registration_date :: Day

84 } deriving (Eq, Show, Generic)

86instance ToJSON User

87```

89Nothing funny going on here. But we now can define our list of two users.

91``` haskell

92users1 :: [User]

93users1 =

94 [ User "Isaac Newton" 372 "isaac@newton.co.uk" (fromGregorian 1683 3 1)

95 , User "Albert Einstein" 136 "ae@mc2.org" (fromGregorian 1905 12 1)

96 ]

97```

99We can now take care of writing the actual webservice that will handle requests

100to such an API. This one will be very simple, being reduced to just a single

101endpoint. The type of the web application is determined by the API type,

102through a *type family* named `Server`. (Type families are just functions that

103take types as input and return types.) The `Server` type family will compute

104the right type that a bunch of request handlers should have just from the

105corresponding API type.

106

107The first thing to know about the `Server` type family is that behind the

108scenes it will drive the routing, letting you focus only on the business

109logic. The second thing to know is that for each endpoint, your handlers will

110by default run in the `Handler` monad. This is overridable very

111easily, as explained near the end of this guide. Third thing, the type of the

112value returned in that monad must be the same as the second argument of the

113HTTP method combinator used for the corresponding endpoint. In our case, it

114means we must provide a handler of type `Handler [User]`. Well,

115we have a monad, let's just `return` our list:

116

117``` haskell

118server1 :: Server UserAPI1

119server1 = return users1

120```

121

122That's it. Now we can turn `server` into an actual webserver using

123[wai](http://hackage.haskell.org/package/wai) and

124[warp](http://hackage.haskell.org/package/warp):

125

126``` haskell

127userAPI :: Proxy UserAPI1

128userAPI = Proxy

129

130-- 'serve' comes from servant and hands you a WAI Application,

131-- which you can think of as an "abstract" web application,

132-- not yet a webserver.

133app1 :: Application

134app1 = serve userAPI server1

135```

136

137The `userAPI` bit is, alas, boilerplate (we need it to guide type inference).

138But that's about as much boilerplate as you get.

139

140And we're done! Let's run our webservice on the port 8081.

141

142``` haskell

143main :: IO ()

144main = run 8081 app1

145```

146

147You can put this all into a file or just grab [servant's

148repo](http://github.com/haskell-servant/servant) and look at the

149*doc/tutorial* directory. This code (the source of this web page) is in

150*doc/tutorial/Server.lhs*.

151

152If you run it, you can go to `http://localhost:8081/users` in your browser or

153query it with curl and you see:

154

155``` bash

156$ curl http://localhost:8081/users

157[{"email":"isaac@newton.co.uk","registration_date":"1683-03-01","age":372,"name":"Isaac Newton"},{"email":"ae@mc2.org","registration_date":"1905-12-01","age":136,"name":"Albert Einstein"}]

158```

159

160## More endpoints

161

162What if we want more than one endpoint? Let's add `/albert` and `/isaac` to

163view the corresponding users encoded in JSON.

164

165``` haskell

166type UserAPI2 = "users" :> Get '[JSON] [User]

167 :<|> "albert" :> Get '[JSON] User

168 :<|> "isaac" :> Get '[JSON] User

169```

170

171And let's adapt our code a bit.

172

173``` haskell

174isaac :: User

175isaac = User "Isaac Newton" 372 "isaac@newton.co.uk" (fromGregorian 1683 3 1)

176

177albert :: User

178albert = User "Albert Einstein" 136 "ae@mc2.org" (fromGregorian 1905 12 1)

179

180users2 :: [User]

181users2 = [isaac, albert]

182```

183

184Now, just like we separate the various endpoints in `UserAPI` with `:<|>`, we

185are going to separate the handlers with `:<|>` too! They must be provided in

186the same order as in the API type.

187

188``` haskell

189server2 :: Server UserAPI2

190server2 = return users2

191 :<|> return albert

192 :<|> return isaac

193```

194

195And that's it! You can run this example in the same way that we showed for

196`server1` and check out the data available at `/users`, `/albert` and `/isaac`.

197

198## From combinators to handler arguments

199

200Fine, we can write trivial webservices easily, but none of the two above use

201any "fancy" combinator from servant. Let's address this and use `QueryParam`,

202`Capture` and `ReqBody` right away. You'll see how each occurrence of these

203combinators in an endpoint makes the corresponding handler receive an

204argument of the appropriate type automatically. You don't have to worry about

205manually looking up URL captures or query string parameters, or

206decoding/encoding data from/to JSON. Never.

207

208We are going to use the following data types and functions to implement a

209server for `API`.

210

211``` haskell

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

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

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

215

216data Position = Position

217 { xCoord :: Int

218 , yCoord :: Int

219 } deriving Generic

220

221instance ToJSON Position

222

223newtype HelloMessage = HelloMessage { msg :: String }

224 deriving Generic

225

226instance ToJSON HelloMessage

227

228data ClientInfo = ClientInfo

229 { clientName :: String

230 , clientEmail :: String

231 , clientAge :: Int

232 , clientInterestedIn :: [String]

233 } deriving Generic

234

235instance FromJSON ClientInfo

236instance ToJSON ClientInfo

237

238data Email = Email

239 { from :: String

240 , to :: String

241 , subject :: String

242 , body :: String

243 } deriving Generic

244

245instance ToJSON Email

246

247emailForClient :: ClientInfo -> Email

248emailForClient c = Email from' to' subject' body'

249

250 where from' = "great@company.com"

251 to' = clientEmail c

252 subject' = "Hey " ++ clientName c ++ ", we miss you!"

253 body' = "Hi " ++ clientName c ++ ",\n\n"

254 ++ "Since you've recently turned " ++ show (clientAge c)

255 ++ ", have you checked out our latest "

256 ++ intercalate ", " (clientInterestedIn c)

257 ++ " products? Give us a visit!"

258```

259

260We can implement handlers for the three endpoints:

261

262``` haskell

263server3 :: Server API

264server3 = position

265 :<|> hello

266 :<|> marketing

267

268 where position :: Int -> Int -> Handler Position

269 position x y = return (Position x y)

270

271 hello :: Maybe String -> Handler HelloMessage

272 hello mname = return . HelloMessage $ case mname of

273 Nothing -> "Hello, anonymous coward"

274 Just n -> "Hello, " ++ n

275

276 marketing :: ClientInfo -> Handler Email

277 marketing clientinfo = return (emailForClient clientinfo)

278```

279

280Did you see that? The types for your handlers changed to be just what we

281needed! In particular:

282

283 - a `Capture "something" a` becomes an argument of type `a` (for `position`);

284 - a `QueryParam "something" a` becomes an argument of type `Maybe a` (because

285an endpoint can technically be accessed without specifying any query

286string parameter, we decided to "force" handlers to be aware that the

287parameter might not always be there);

288

289 - a `ReqBody contentTypeList a` becomes an argument of type `a`;

290

291And that's it. Here's the example in action:

292

293``` bash

294$ curl http://localhost:8081/position/1/2

295{"xCoord":1,"yCoord":2}

296$ curl http://localhost:8081/hello

297{"msg":"Hello, anonymous coward"}

298$ curl http://localhost:8081/hello?name=Alp

299{"msg":"Hello, Alp"}

300$ curl -X POST -d '{"clientName":"Alp Mestanogullari", "clientEmail" : "alp@foo.com", "clientAge": 25, "clientInterestedIn": ["haskell", "mathematics"]}' -H 'Accept: application/json' -H 'Content-type: application/json' http://localhost:8081/marketing

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

302```

303

304For reference, here's a list of some combinators from **servant**:

305

306 > - `Delete`, `Get`, `Patch`, `Post`, `Put`: these do not become arguments. They provide the return type of handlers, which usually is `Handler <something>`.

307 > - `Capture "something" a` becomes an argument of type `a`.

308 > - `QueryParam "something" a`, `Header "something" a` all become arguments of type `Maybe a`, because there might be no value at all specified by the client for these.

309 > - `QueryFlag "something"` gets turned into an argument of type `Bool`.

310 > - `QueryParams "something" a` gets turned into an argument of type `[a]`.

311 > - `ReqBody contentTypes a` gets turned into an argument of type `a`.

312

313## The `FromHttpApiData`/`ToHttpApiData` classes

314

315Wait... How does **servant** know how to decode the `Int`s from the URL? Or how

316to decode a `ClientInfo` value from the request body? The following three sections will

317help us answer these questions.

318

319`Capture`s and `QueryParam`s are represented by some textual value in URLs.

320`Header`s are similarly represented by a pair of a header name and a