Servant
Servant type-level web API patterns for building type-safe HTTP services with compile-time route validation in Haskell
Details
Language / Topic
HaskellCategory
framework
Compatible Frameworks
servant
Rules
balanced
- Define the API as a type: `type UserAPI = "users" :> Get '[JSON] [User] :<|> "users" :> ReqBody '[JSON] NewUser :> Post '[JSON] User`.
- Use `hoistServer` to run a custom monad: `hoistServer (Proxy :: Proxy API) (runApp env) server` with a natural transformation `AppM a -> Handler a`.
- Use `Capture "id" UserId` for path segments, `QueryParam "page" Int` for optional query params, `Header "X-Token" Text` for headers.
- Generate typed clients: `let getUsers :<|> createUser = client (Proxy :: Proxy UserAPI)` — never write HTTP calls manually for a typed API.
- Add `servant-auth-server` for JWT: `Auth '[JWT, Cookie] AuthUser :> ProtectedAPI` — protect routes at the type level.
- Generate OpenAPI spec with `servant-openapi3`: derive `ToSchema` via `Generic` and expose at `/openapi.json`.
- Structure large APIs: `type FullAPI = "v1" :> (UserAPI :<|> PostAPI)` — combine handlers with the `:<|>` combinator.
- Return custom errors by mapping domain exceptions to `ServerError` in the `hoistServer` natural transformation.