doc/tutorial/ApiType.lhs · servant

git.iko.soy/servant

on 58ccae1 help sign in

servant/doc/tutorial/ApiType.lhs

385 lines 14 kB history raw

1# A web API as a type

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

4need to have some language extensions and imports:

6``` haskell

7{-# LANGUAGE DataKinds #-}

8{-# LANGUAGE TypeOperators #-}

10module ApiType where

12import Data.Text

13import Data.Time (UTCTime)

14import Servant.API

15```

17Consider the following informal specification of an API:

19 > The endpoint at `/users` expects a GET request with query string parameter

20 > `sortby` whose value can be one of `age` or `name` and returns a

21 > list/array of JSON objects describing users, with fields `age`, `name`,

22 > `email`, `registration_date`".

24You *should* be able to formalize that. And then use the formalized version to

25get you much of the way towards writing a web app. And all the way towards

26getting some client libraries, and documentation, and more.

28How would we describe it with **servant**? An endpoint description is a good old

29Haskell **type**:

31``` haskell

32type UserAPI = "users" :> QueryParam "sortby" SortBy :> Get '[JSON] [User]

34data SortBy = Age | Name

36data User = User {

37 name :: String,

38 age :: Int,

39 email :: String,

40 registration_date :: UTCTime

41}

42```

44Let's break that down:

46- `"users"` says that our endpoint will be accessible under `/users`;

47- `QueryParam "sortby" SortBy`, where `SortBy` is defined by `data SortBy = Age | Name`,

48 says that the endpoint has a query string parameter named `sortby`

49 whose value will be extracted as a value of type `SortBy`.

50- `Get '[JSON] [User]` says that the endpoint will be accessible through HTTP

51 GET requests, returning a list of users encoded as JSON. You will see

52 later how you can make use of this to make your data available under different

53 formats, the choice being made depending on the [Accept

54 header](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html) specified in

55 the client's request.

56- The `:>` operator that separates the various "combinators" just lets you

57 sequence static path fragments, URL captures and other combinators. The

58 ordering only matters for static path fragments and URL captures. `"users" :>

59 "list-all" :> Get '[JSON] [User]`, equivalent to `/users/list-all`, is

60 obviously not the same as `"list-all" :> "users" :> Get '[JSON] [User]`, which

61 is equivalent to `/list-all/users`. This means that sometimes `:>` is somehow

62 equivalent to `/`, but sometimes it just lets you chain another combinator.

64Tip: If your endpoint responds to `/` (the root path), just omit any combinators

65that introduce path segments. E.g. the following api has only one endpoint on `/`:

67``` haskell

68type RootEndpoint =

69 Get '[JSON] User

70```

72We can also describe APIs with multiple endpoints by using the `:<|>`

73combinators. Here's an example:

75``` haskell

76type UserAPI2 = "users" :> "list-all" :> Get '[JSON] [User]

77 :<|> "list-all" :> "users" :> Get '[JSON] [User]

78```

80**servant** provides a fair amount of combinators out-of-the-box, but you can

81always write your own when you need it. Here's a quick overview of the most

82often needed combinators that **servant** comes with.

84## Combinators

86### Static strings

88As you've already seen, you can use type-level strings (enabled with the

89`DataKinds` language extension) for static path fragments. Chaining

90them amounts to `/`-separating them in a URL.

92``` haskell

93type UserAPI3 = "users" :> "list-all" :> "now" :> Get '[JSON] [User]

94 -- describes an endpoint reachable at:

95 -- /users/list-all/now

96```

98### `Delete`, `Get`, `Patch`, `Post` and `Put`

100The `Get` combinator is defined in terms of the more general `Verb`:

101``` haskell ignore

102data Verb method (statusCode :: Nat) (contentType :: [*]) a

103type Get = Verb 'GET 200

104```

105

106There are other predefined type synonyms for other common HTTP methods,

107such as e.g.:

108``` haskell ignore

109type Delete = Verb 'DELETE 200

110type Patch = Verb 'PATCH 200

111type Post = Verb 'POST 200

112type Put = Verb 'PUT 200

113```

114

115There are also variants that do not return a 200 status code, such

116as for example:

117``` haskell ignore

118type PostCreated = Verb 'POST 201

119type PostAccepted = Verb 'POST 202

120```

121

122An endpoint always ends with a variant of the `Verb` combinator

123(unless you write your own combinators). Examples:

124

125``` haskell

126type UserAPI4 = "users" :> Get '[JSON] [User]

127 :<|> "admins" :> Get '[JSON] [User]

128```

129

130### `StreamGet` and `StreamPost`

131

132The `StreamGet` and `StreamPost` combinators are defined in terms of the more general `Stream`

133

134``` haskell ignore

135data Stream (method :: k1) (framing :: *) (contentType :: *) a

136type StreamGet = Stream 'GET

137type StreamPost = Stream 'POST

138```

139

140These describe endpoints that return a stream of values rather than just a single value. They not only take a single content type as a parameter, but also a framing strategy -- this specifies how the individual results are delineated from one another in the stream. The three standard strategies given with Servant are `NewlineFraming`, `NetstringFraming` and `NoFraming`, but others can be written to match other protocols.

141

142

143### `Capture`

144

145URL captures are segments of the path of a URL that are variable and whose actual value is

146captured and passed to the request handlers. In many web frameworks, you'll see

147it written as in `/users/:userid`, with that leading `:` denoting that `userid`

148is just some kind of variable name or placeholder. For instance, if `userid` is

149supposed to range over all integers greater or equal to 1, our endpoint will

150match requests made to `/users/1`, `/users/143` and so on.

151

152The `Capture` combinator in **servant** takes a (type-level) string representing