Type-Safe Web APIs with Servant in Haskell

Chapter 2
The Servant Ecosystem: Concepts and Architecture

Imagine describing your entire web API as a single type-and letting the compiler ensure every contract, every route, and every serialization detail lines up perfectly. In this chapter, you'll unravel the heart of Servant, Haskell's pioneering framework for type-driven web service design. We dissect the architecture, mechanics, and composition models behind Servant, empowering you to harness its sophisticated abstractions for building precise, maintainable, and evolvable APIs.

2.1 Servant's Type-Level DSL

The Servant library represents web APIs using a rich, statically checked domain-specific language (DSL) at the type level, empowering Haskell programmers to express interface contracts precisely and leverage the compiler to enforce correctness. This type-level DSL interleaves routes, HTTP methods, content types, and combinators into comprehensive API specifications whose structure guides the implementation of handlers and client code. The core innovation is encoding API semantics within types, enabling type-directed programming where the specification itself is a first-class artifact, fully verified at compile time.

At its foundation, Servant's DSL models an API as a composition of endpoint descriptions, each constructed by combining type-level elements representing URL captures, HTTP verbs, and request or response content. These elements collectively form a type that corresponds to the entire API. This construction is fundamentally a coproduct of products: routes form sums (choice between paths), while HTTP methods and associated data form products (elements combined in sequence). This duality affords expressivity and modularity in API representation.

Routes correspond to path segments in the API's URL space. The simplest route element is a static path segment, encoded as a type-level string using the Symbol kind. This is expressed via the path combinator, which matches a single literal component of the URL path. For example,

represents an endpoint under the path segment "books".

Dynamic path components, essential for parameterizing requests, are captured by Capture combinators, which associate a path segment with a typed value extracted from the URL. For instance,

specifies that the path contains a dynamic segment named "bookId", parsed as an Int.

Path segments combine readily with combinators using the composition operator :>, chaining static and dynamic components to represent routes with arbitrary complexity. The endpoint is fully specified when methods and response types are appended, bridging the URL structure with HTTP semantics and data handling.

Each route culminates in an HTTP method combinator that captures the semantic intent of interaction: Get, Post, Put, Delete, and others wrap the route specification and specify how the server responds.

These method combinators include type parameters representing the content types accepted for the request and returned in the response. The response content type is encoded as a list of types under the Accept kind when applicable; e.g., Get '[JSON] MyResponseType specifies that the endpoint returns a JSON-encoded MyResponseType.

The ReqBody combinator expresses request payloads, indicating that the request contains a body of a specific content type and Haskell type. This type-level encoding allows the API type to precisely capture both input and output data formats, ensuring the compiler verifies conformance.

Content types are key to serializing and deserializing HTTP payloads. Servant encodes content types at the type level via empty data types (phantom types), such as JSON, PlainText, and FormUrlEncoded. These are used as parameters to method combinators and ReqBody to specify which formats the server can consume or produce.

The typeclass machinery behind these phantom types ensures that appropriate instances of FromJSON or ToJSON (or analogous serializers) are available, enforcing that only supported content types are used for each endpoint. Consequently, the API type guarantees consistency between the declared content types and the actual data serialization implementations.

Servant's DSL provides several combinators to build composite APIs:

• :<|> combines multiple endpoints into a type-level sum, representing a choice between routes or methods. For example,

  type API = Get '[JSON] FooData :<|> Post '[JSON] BarData

  specifies an API with two distinct endpoints, a GET and a POST.

• :> sequences URL components and modifiers into an endpoint path:

  "users" :> Capture "userid" Int :> Get '[JSON] User

  represents a GET endpoint at /users/:userid returning a User encoded as JSON.

• BasicAuth and similar combinators model common authentication schemes at the type level, integrating security requirements into the API contract.
• Combinators for query parameters (QueryParam, QueryParams) and headers (Header) embed HTTP metadata into the type signature, clarifying which data is expected from clients.

These combinators are right associative, and the entire API type expression thus forms a domain-specific language embedded within Haskell's type system.

The power of Servant's type-level DSL lies in its ability to drive not only API specification but also implementations for servers and clients. The API type acts as a blueprint from which Servant derives server handler types, client functions, documentation, and even mock servers through typeclass instances.

For example, the type-level specification's static guarantees ensure that server implementations cannot diverge from the declared routes, methods, or data formats. This tight coupling eliminates runtime errors due to mismatch or ambiguity between API contract and code, as such discrepancies manifest during compilation.

Handlers for a defined API must conform to the types induced by it: the combination of route captures, query parameters, request bodies, and the expected response type specifies the function signature for each endpoint's implementation. The type system ensures that all necessary inputs are accounted for and that responses are properly formed.

Consider the following snippet expressing a rudimentary API: