@@ -2,7 +2,7 @@
22
33While defining handlers that serve an API 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. Except that 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 a bunch of client-side functions.
44
5−*servant* however has a way to inspect API, 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 occurence of `Capture`, `ReqBody`, `QueryParam`
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 occurence of `Capture`, `ReqBody`, `QueryParam`
66and friends. By *derive*, we mean that there's no code generation involved, the functions are defined just by the structure of the API type.
77
88The source for this tutorial section is a literate haskell file, so first we
@@ -67,7 +67,7 @@ type API = "position" :> Capture "x" Int :> Capture "y" Int :> Get '[JSON] Posit
6767 :<|> "marketing" :> ReqBody '[JSON] ClientInfo :> Post '[JSON] Email
6868```
6969
70−What we are going to get with *servant-client* here is 3 functions, one to query each endpoint:
70+What we are going to get with **servant-client** here is 3 functions, one to query each endpoint:
7171
7272``` haskell
7373position :: Int -- ^ value for "x"
@@ -81,7 +81,15 @@ marketing :: ClientInfo -- ^ value for the request body
8181 -> ExceptT ServantError IO Email
8282```
8383
84−Each function makes available as an argument any value that the response may depend on, as evidenced in the API type. How do we get these functions? Just give a `Proxy` to your API and a host to make the requests to:
84+Each function makes available as an argument any value that the response may
85+depend on, as evidenced in the API type. How do we get these functions? By calling
86+the function `client`. It takes three arguments:
87+
88+- a `Proxy` to your API,
89+- a `BaseUrl`, consisting of the protocol, the host, the port and an optional subpath --
90+ this basically tells `client` where the service that you want to query is hosted,
91+- a `Manager`, (from [http-client](http://hackage.haskell.org/package/http-client))
92+which manages http connections.
8593
8694``` haskell
8795api :: Proxy API
@@ -95,6 +103,9 @@ position :<|> hello :<|> marketing =
95103 client api (BaseUrl Http "localhost" 8081 "") __manager
96104```
97105
106+(Yes, the usage of `unsafePerformIO` is very ugly, we know. Hopefully soon it'll
107+be possible to do without.)
108+
98109As you can see in the code above, we just "pattern match our way" to these functions. If we try to derive less or more functions than there are endpoints in the API, we obviously get an error. The `BaseUrl` value there is just:
99110
100111``` haskell ignore
@@ -134,16 +145,12 @@ run = do
134145 print em
135146```
136147
137−You can now run `dist/build/tutorial/tutorial 8` (the server) and
138−`dist/build/t8-main/t8-main` (the client) to see them both in action.
148+Here's the output of the above code running against the appropriate server:
139149
140150``` bash
141− $ dist/build/tutorial/tutorial 8
142− # and in another terminal:
143− $ dist/build/t8-main/t8-main
144− Position {x = 10, y = 10}
145− HelloMessage {msg = "Hello, servant"}
146− Email {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!"}
151+Position {x = 10, y = 10}
152+HelloMessage {msg = "Hello, servant"}
153+Email {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!"}
147154```
148155
149−The types of the arguments for the functions are the same as for (server-side) request handlers. You now know how to use *servant-client*!
156+The types of the arguments for the functions are the same as for (server-side) request handlers. You now know how to use **servant-client**!