Documentation

The server for an EmptyAPI is emptyServer.

type MyApi = "nothing" :> EmptyApi

server :: Server MyApi
server = emptyServer

Just pass the request to the underlying application and serve its response.

Example:

type MyApi = "images" :> Raw

server :: Server MyApi
server = serveDirectory "/var/www/images"

Just pass the request to the underlying application and serve its response.

Example:

type MyApi = "images" :> Raw

server :: Server MyApi
server = serveDirectory "/var/www/images"

A server for a :<|> b first tries to match the request against the route represented by a and if it fails tries b. You must provide a request handler for each route.

type MyApi = "books" :> Get '[JSON] [Book] -- GET /books
        :<|> "books" :> ReqBody Book :> Post '[JSON] Book -- POST /books

server :: Server MyApi
server = listAllBooks :<|> postBook
  where listAllBooks = ...
        postBook book = ...

This instance prevents from accidentally using -> instead of :>

>>> serve (Proxy :: Proxy (Capture "foo" Int -> Get '[JSON] Int)) (error "...")
...
...No instance HasServer (a -> b).
...Maybe you have used '->' instead of ':>' between
...Capture' '[] "foo" Int
...and
...Verb 'GET 200 '[JSON] Int
...

>>> undefined :: Server (Capture "foo" Int -> Get '[JSON] Int)
...
...No instance HasServer (a -> b).
...Maybe you have used '->' instead of ':>' between
...Capture' '[] "foo" Int
...and
...Verb 'GET 200 '[JSON] Int
...

Make sure the incoming request starts with "/path", strip it and pass the rest of the request path to api.

Basic Authentication

If you use Capture in one of the endpoints for your API, this automatically requires your server-side handler to be a function that takes an argument of the type specified by the Capture. This lets servant worry about getting it from the URL and turning it into a value of the type you specify.

You can control how it'll be converted from Text to your type by simply providing an instance of FromHttpApiData for your type.

Example:

type MyApi = "books" :> Capture "isbn" Text :> Get '[JSON] Book

server :: Server MyApi
server = getBook
  where getBook :: Text -> Handler Book
        getBook isbn = ...

If you use CaptureAll in one of the endpoints for your API, this automatically requires your server-side handler to be a function that takes an argument of a list of the type specified by the CaptureAll. This lets servant worry about getting values from the URL and turning them into values of the type you specify.

You can control how they'll be converted from Text to your type by simply providing an instance of FromHttpApiData for your type.

Example:

type MyApi = "src" :> CaptureAll "segments" Text :> Get '[JSON] SourceFile

server :: Server MyApi
server = getSourceFile
  where getSourceFile :: [Text] -> Handler Book
        getSourceFile pathSegments = ...

Ignore Description in server handlers.

Ignore Summary in server handlers.

Ignore EmptyAPI as part of route in server handlers.

Known orphan instance.

Ignore Fragment in server handlers. See https://ietf.org/rfc/rfc2616.html#section-15.1.3 for more details.

Example:

type MyApi = "books" :> Fragment Text :> Get '[JSON] [Book]

server :: Server MyApi
server = getBooks
  where getBooks :: Handler [Book]
        getBooks = ...return all books...

If you use Header in one of the endpoints for your API, this automatically requires your server-side handler to be a function that takes an argument of the type specified by Header. This lets servant worry about extracting it from the request and turning it into a value of the type you specify.

All it asks is for a FromHttpApiData instance.

Example:

newtype Referer = Referer Text
  deriving (Eq, Show, FromHttpApiData)

           -- GET /view-my-referer
type MyApi = "view-my-referer" :> Header "Referer" Referer :> Get '[JSON] Referer

server :: Server MyApi
server = viewReferer
  where viewReferer :: Referer -> Handler referer
        viewReferer referer = return referer

If you use QueryFlag "published" in one of the endpoints for your API, this automatically requires your server-side handler to be a function that takes an argument of type Bool.

Example:

type MyApi = "books" :> QueryFlag "published" :> Get '[JSON] [Book]

server :: Server MyApi
server = getBooks
  where getBooks :: Bool -> Handler [Book]
        getBooks onlyPublished = ...return all books, or only the ones that are already published, depending on the argument...

If you use QueryParam "author" Text in one of the endpoints for your API, this automatically requires your server-side handler to be a function that takes an argument of type Maybe Text.

This lets servant worry about looking it up in the query string and turning it into a value of the type you specify, enclosed in Maybe, because it may not be there and servant would then hand you Nothing.

You can control how it'll be converted from Text to your type by simply providing an instance of FromHttpApiData for your type.

Example:

type MyApi = "books" :> QueryParam "author" Text :> Get '[JSON] [Book]

server :: Server MyApi
server = getBooksBy
  where getBooksBy :: Maybe Text -> Handler [Book]
        getBooksBy Nothing       = ...return all books...
        getBooksBy (Just author) = ...return books by the given author...

If you use QueryParams "authors" Text in one of the endpoints for your API, this automatically requires your server-side handler to be a function that takes an argument of type [Text].

This lets servant worry about looking up 0 or more values in the query string associated to authors and turning each of them into a value of the type you specify.

You can control how the individual values are converted from Text to your type by simply providing an instance of FromHttpApiData for your type.

Example:

type MyApi = "books" :> QueryParams "authors" Text :> Get '[JSON] [Book]

server :: Server MyApi
server = getBooksBy
  where getBooksBy :: [Text] -> Handler [Book]
        getBooksBy authors = ...return all books by these authors...

If you use DeepQuery "symbol" a in one of the endpoints for your API, this automatically requires your server-side handler to be a function that takes an argument of type a.

This lets you extract an object from multiple parameters in the query string, with its fields enclosed in brackets: `/books?filter[author][name]=value`. When all the fields are known in advance, it can be done with QueryParam (it can still be tedious if you the object has many fields). When some fields are dynamic, it cannot be done with @QueryParam.

The way the object is constructed from the extracted fields can be controlled by providing an instance on FromDeepQuery

Example:

type MyApi = "books" :> DeepQuery "filter" BookQuery :> Get '[JSON] [Book]

server :: Server MyApi
server = getBooksBy
  where getBooksBy :: BookQuery -> Handler [Book]
        getBooksBy query = ...filter books based on the dynamic filters provided...

If you use QueryString in one of the endpoints for your API, this automatically requires your server-side handler to be a function that takes an argument of type Query ([(ByteString, Maybe ByteString)]).

This lets you extract the whole query string. This is useful when the query string can contain parameters with dynamic names, that you can't access with QueryParam.

Example:

type MyApi = "books" :> QueryString :> Get '[JSON] [Book]

server :: Server MyApi
server = getBooksBy
  where getBooksBy :: Query -> Handler [Book]
        getBooksBy filters = ...filter books based on the dynamic filters provided...

If you use ReqBody in one of the endpoints for your API, this automatically requires your server-side handler to be a function that takes an argument of the type specified by ReqBody. The Content-Type header is inspected, and the list provided is used to attempt deserialization. If the request does not have a Content-Type header, it is treated as application/octet-stream (as specified in RFC 7231 section 3.1.1.5). This lets servant worry about extracting it from the request and turning it into a value of the type you specify.

All it asks is for a FromJSON instance.

Example:

type MyApi = "books" :> ReqBody '[JSON] Book :> Post '[JSON] Book

server :: Server MyApi
server = postBook
  where postBook :: Book -> Handler Book
        postBook book = ...insert into your db...

If you use WithResource in one of the endpoints for your API Servant will provide the handler for this endpoint an argument of the specified type. The lifespan of this resource will be automatically managed by Servant. This resource will be created before the handler starts and it will be destoyed after it ends. A new resource is created for each request to the endpoint.