8b993b9 · servant · git.iko.soy

doc/tutorial/ApiType.lhs+2−1

compare with master

unifiedsplit

@@ -345,7 +345,8 @@ type UserAPI12Alone = UserAPI12 EmptyAPI

345```

346

347This also works well as a placeholder for unfinished parts of an API while it

348−is under development.

348+is under development, for when you know that there should be _something_ there

349+but you don't yet know what. Think of it as similar to the unit type `()`.

349

350

350### Interoperability with `wai`: `Raw`

351### Interoperability with `wai`: `Raw`

351

352

doc/tutorial/Client.lhs+3−2

@@ -93,8 +93,9 @@ position :<|> hello :<|> marketing = client api

93

94`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.

95

96−If there is an `EmptyAPI` within your API, this matches the `EmptyClient`

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

97−constructor:

97+type `EmptyClient` in the corresponding slot, where `data EmptyClient =

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

98

99

99``` haskell ignore

100``` haskell ignore

100type API' = API :<|> EmptyAPI

101type API' = API :<|> EmptyAPI

doc/tutorial/Docs.lhs+2

@@ -89,6 +89,8 @@ instance ToSample Email where

89```

90

91Types that are used as request or response bodies have to instantiate the `ToSample` typeclass which lets you specify one or more examples of values. `Capture`s and `QueryParam`s have to instantiate their respective `ToCapture` and `ToParam` classes and provide a name and some information about the concrete meaning of that argument, as illustrated in the code above.

92+The `EmptyAPI` combinator needs no special treatment as it generates no

93+documentation: an empty API has no endpoints to document.

92

94

93With all of this, we can derive docs for our API.

95With all of this, we can derive docs for our API.

94

96

doc/tutorial/Javascript.lhs+3

@@ -149,6 +149,9 @@ Why two different API types, proxies and servers though? Simply because we

149don't want to generate javascript functions for the `Raw` part of our API type,

150so we need a `Proxy` for our API type `API'` without its `Raw` endpoint.

151

152+The `EmptyAPI` combinator needs no special treatment as it generates no

153+Javascript functions: an empty API has no endpoints to access.

154+

152Very similarly to how one can derive haskell functions, we can derive the

155Very similarly to how one can derive haskell functions, we can derive the

153javascript with just a simple function call to `jsForAPI` from

156javascript with just a simple function call to `jsForAPI` from

154`Servant.JS`.

157`Servant.JS`.

doc/tutorial/Server.lhs+3−2

@@ -1020,8 +1020,9 @@ serverFor = error "..."

1020-- or the mailing list if you get stuck!

1021```

1022

1023−If the API contains the `EmptyAPI` combinator, the corresponding server is

1023+When your API contains the `EmptyAPI` combinator, you'll want to use

1024−called `emptyServer`:

1024+`emptyServer` in the corresponding slot for your server, which will simply fail

1025+with 404 whenever a request reaches it:

1025

1026

1026``` haskell

1027``` haskell

1027type CombinedAPI2 = API :<|> "empty" :> EmptyAPI

1028type CombinedAPI2 = API :<|> "empty" :> EmptyAPI