servant/doc/tutorial/Client.lhs

201 lines
6.9 KiB
Text
Raw Normal View History

2016-02-18 18:13:43 +01:00
# Querying an API
2016-01-25 14:11:40 +01:00
While defining handlers that [serve an API](Server.lhs) 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.
2016-01-25 14:11:40 +01:00
**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`
and friends (see [the tutorial introduction](ApiType.lhs) 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.
2016-01-25 14:11:40 +01:00
The source for this tutorial section is a literate Haskell file, so first we need to have some language extensions and imports:
2016-01-25 14:11:40 +01:00
2016-01-27 22:28:58 +01:00
``` haskell
{-# LANGUAGE DataKinds #-}
{-# LANGUAGE DeriveGeneric #-}
{-# LANGUAGE TypeOperators #-}
module Client where
import Data.Aeson
import Data.Proxy
import GHC.Generics
import Network.HTTP.Client (newManager, defaultManagerSettings)
2016-01-27 22:28:58 +01:00
import Servant.API
import Servant.Client
```
2016-01-25 14:11:40 +01:00
Also, we need examples for some domain specific data types:
2016-01-27 22:28:58 +01:00
``` haskell
data Position = Position
{ xCoord :: Int
, yCoord :: Int
2016-01-27 22:28:58 +01:00
} deriving (Show, Generic)
instance FromJSON Position
newtype HelloMessage = HelloMessage { msg :: String }
deriving (Show, Generic)
instance FromJSON HelloMessage
data ClientInfo = ClientInfo
{ clientName :: String
, clientEmail :: String
, clientAge :: Int
, clientInterestedIn :: [String]
} deriving Generic
instance ToJSON ClientInfo
data Email = Email
{ from :: String
, to :: String
, subject :: String
, body :: String
} deriving (Show, Generic)
instance FromJSON Email
```
2016-01-25 14:11:40 +01:00
Enough chitchat, let's see an example. Consider the following API type from the previous section:
2016-01-27 22:28:58 +01:00
``` haskell
type API = "position" :> Capture "x" Int :> Capture "y" Int :> Get '[JSON] Position
:<|> "hello" :> QueryParam "name" String :> Get '[JSON] HelloMessage
:<|> "marketing" :> ReqBody '[JSON] ClientInfo :> Post '[JSON] Email
```
2016-01-25 14:11:40 +01:00
What we are going to get with **servant-client** here is three functions, one to query each endpoint:
2016-01-25 14:11:40 +01:00
2016-01-27 22:28:58 +01:00
``` haskell
position :: Int -- ^ value for "x"
-> Int -- ^ value for "y"
-> ClientM Position
2016-01-27 22:28:58 +01:00
hello :: Maybe String -- ^ an optional value for "name"
-> ClientM HelloMessage
2016-01-27 22:28:58 +01:00
marketing :: ClientInfo -- ^ value for the request body
-> ClientM Email
2016-01-27 22:28:58 +01:00
```
2016-01-25 14:11:40 +01:00
2016-02-28 22:16:43 +01:00
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? By calling
the function `client`. It takes one argument:
2016-02-28 22:16:43 +01:00
- a `Proxy` to your API,
2016-01-25 14:11:40 +01:00
2016-01-27 22:28:58 +01:00
``` haskell
api :: Proxy API
api = Proxy
2017-05-17 07:50:38 +02:00
position :<|> hello :<|> marketing = client api
2016-01-27 22:28:58 +01:00
```
2016-01-25 14:11:40 +01:00
`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.
2016-01-25 14:11:40 +01:00
2017-05-17 10:24:04 +02:00
If you have an `EmptyAPI` in your API, servant-client will hand you a value of
type `EmptyClient` in the corresponding slot, where `data EmptyClient =
EmptyClient`, as a way to indicate that you can't do anything useful with it.
2017-05-17 07:50:38 +02:00
``` haskell ignore
type API' = API :<|> EmptyAPI
api' :: Proxy API'
api' = Proxy
(position' :<|> hello' :<|> marketing') :<|> EmptyClient = client api'
```
2016-01-27 22:26:59 +01:00
``` haskell ignore
2016-01-25 14:11:40 +01:00
-- | URI scheme to use
data Scheme =
Http -- ^ http://
| Https -- ^ https://
deriving
-- | Simple data type to represent the target of HTTP requests
-- for servant's automatically-generated clients.
data BaseUrl = BaseUrl
{ baseUrlScheme :: Scheme -- ^ URI scheme to use
, baseUrlHost :: String -- ^ host (eg "haskell.org")
, baseUrlPort :: Int -- ^ port (eg 80)
, baseUrlPath :: String -- ^ path (eg "/a/b/c")
2016-01-25 14:11:40 +01:00
}
```
That's it. Let's now write some code that uses our client functions.
2016-01-27 22:28:58 +01:00
``` haskell
queries :: ClientM (Position, HelloMessage, Email)
queries = do
2017-09-13 22:01:31 +02:00
pos <- position 10 10
message <- hello (Just "servant")
em <- marketing (ClientInfo "Alp" "alp@foo.com" 26 ["haskell", "mathematics"])
2016-01-28 13:22:20 +01:00
return (pos, message, em)
2016-01-27 22:28:58 +01:00
run :: IO ()
run = do
2017-09-13 22:01:31 +02:00
manager' <- newManager defaultManagerSettings
res <- runClientM queries (mkClientEnv manager' (BaseUrl Http "localhost" 8081 ""))
2016-01-27 22:28:58 +01:00
case res of
Left err -> putStrLn $ "Error: " ++ show err
2016-01-28 13:22:20 +01:00
Right (pos, message, em) -> do
2016-01-27 22:28:58 +01:00
print pos
2016-01-28 13:22:20 +01:00
print message
2016-01-27 22:28:58 +01:00
print em
```
2016-01-25 14:11:40 +01:00
2016-02-28 22:16:43 +01:00
Here's the output of the above code running against the appropriate server:
2016-01-25 14:11:40 +01:00
```
Position {xCoord = 10, yCoord = 10}
2016-02-28 22:16:43 +01:00
HelloMessage {msg = "Hello, servant"}
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!"}
2016-01-25 14:11:40 +01:00
```
The types of the arguments for the functions are the same as for (server-side) request handlers.
## Querying Streaming APIs.
Consider the following streaming API type:
``` haskell
type StreamAPI = "positionStream" :> StreamGet NewlineFraming JSON (ResultStream Position)
```
Note that when we declared an API to serve, we specified a `StreamGenerator` as a producer of streams. Now we specify our result type as a `ResultStream`. With types that can be used both ways, if appropriate adaptors are written (in the form of `ToStreamGenerator` and `BuildFromStream` instances), then this asymmetry isn't necessary. Otherwise, if you want to share the same API across clients and servers, you can parameterize it like so:
``` haskell ignore
type StreamAPI f = "positionStream" :> StreamGet NewlineFraming JSON (f Position)
type ServerStreamAPI = StreamAPI StreamGenerator
type ClientStreamAPI = StreamAPI ResultStream
```
In any case, here's how we write a function to query our API:
``` haskell
streamAPI :: Proxy StreamAPI
streamAPI = Proxy
posStream :: ClientM (ResultStream Position)
posStream = client streamAPI
```
And here's how to just print out all elements from a `ResultStream`, to give some idea of how to work with them.
``` haskell
printResultStream :: Show a => ResultStream a -> IO ()
printResultStream (ResultStream k) = k $ \getResult ->
let loop = do
r <- getResult
case r of
Nothing -> return ()
Just x -> print x >> loop
in loop
```
The stream is parsed and provided incrementally. So the above loop prints out each result as soon as it is received on the stream, rather than waiting until they are all available to print them at once.
You now know how to use **servant-client**!