A simple representation of a single endpoint of an API.

Given a REST Method, create a default Route: root path ("/") with no params, headers, body, auths, or response.

Pretty-print a Route. Note that the output is minimal and doesn't contain all the information contained in a Route. For full output, use the ToJSON instance.

ghci> renderRoute $ defRoute \"POST\"
"POST /"
ghci> :{
ghci| renderRoute $
ghci|   defRoute \"POST\"
ghci|     & routePath %~ prependPathPart "api/v2"
ghci|     & routeParams .~ [singleParam @"p1" @T.Text, flagParam @"flag", arrayElemParam @"p2s" @(Maybe Int)]
ghci| :}
"POST /api/v2?p1=<Text>&flag&p2s=<[Maybe Int]>"

To render all of an API's Routes as JSON, we need to identify each route by its path AND its method (since 2 routes can have the same path but different method). This newtype lets us represent this nested structure.

Get the underlying Map of a Routes.

A smart constructor that allows us to think of a Routes as simply a list of Routes, whereas it's actually a Map.

Get a simple list of all the routes in an API.

One use-case, which was the original motivation for the class, is refactoring Servant APIs to use NamedRoutes. It's a fiddly, repetitive, and error-prone process, and it's very easy to make small mistakes. A lot of these errors will be caught by the type-checker, e.g. if the type signature of a handler function doesn't match the ServerT of its API type. However there are some errrors that wouldn't be caught by the type-checker, such as missing out path parts.

For example, if our original API looked like

type API =
  "api"
    :> "v2"
    :> ( "users" :> Get '[JSON] [User]
          :<|> "user" :> ReqBody '[JSON] UserData :> Post '[JSON] UserId
       )

server :: Server API
server = listUsers :<|> createUser
  where ...

and we refactored to

data RefactoredAPI mode = RefactoredAPI
  { listUsers :: mode :- "api" :> "v2" :> "users" :> Get '[JSON] [User]
  , createUser :: mode :- "user" :> ReqBody '[JSON] UserData :> Post '[JSON] UserId
  }
  deriving Generic

server :: Server (NamedRoutes RefactoredAPI)
server = RefactoredAPI {listUsers, createUser}
  where ...

Oops! We forgot the "api" :> "v2" :> in the 2nd sub-endpoint. However, since the ServerT type is unaffected by adding or remove path parts, this will still compile.

However, if we use HasRoutes as a sanity check:

ghci> printRoutes @API
GET /api/v2/users
POST /api/v2/user

ghci> printRoutes @(NamedRoutes RefactoredAPI)
GET /api/v2/users
POST /user

Much clearer to see the mistake. For more detailed output, use the ToJSON instance:

ghci> BL.putStrLn . encodePretty $ getRoutes @API
[
    {
        "auths": [],
        "method": "GET",
        "params": [],
        "path": "/api/v2/users",
        "request_body": null,
        "request_headers": [],
        "response": "[User]",
        "response_headers": []
    },
    {
        "auths": [],
        "method": "POST",
        "params": [],
        "path": "/api/v2/user",
        "request_body": "UserData",
        "request_headers": [],
        "response": "UserId",
        "response_headers": []
    }
]

ghci> BL.putStrLn . encodePretty $ getRoutes @(NamedRoutes RefactoredAPI)
[
    {
        "auths": [],
        "method": "GET",
        "params": [],
        "path": "/api/v2/users",
        "request_body": null,
        "request_headers": [],
        "response": "[User]",
        "response_headers": []
    },
    {
        "auths": [],
        "method": "POST",
        "params": [],
        "path": "/user",              -- oops!
        "request_body": "UserData",
        "request_headers": [],
        "response": "UserId",
        "response_headers": []
    }
]

Get all the routes of an API and print them to stdout. See renderRoute for examples.

Same as printRoutes, but encode the Routes as JSON before printing to stdout. For an even prettier version, see printRoutesJSONPretty.

Pretty-encode the Routes as JSON before printing to stdout.

Simple representation of a URL path.

"/"

Prepend a simple text path part to an API path.

For example, prependPathPart "api" will transform /v2/users to /api/v2/users.

Prepend a capture path part of a given type to an API path. Equivalent to Capture name a :>.

For example, prependCapturePart @Int "id" will transform /detail to /<Int>/detail.

Prepend a capture-all path part of a given type to an API path. Equivalent to CaptureAll name a :>.

For example, prependCaptureAllPart @Int "id" will transform /detail to /<[Int]>/detail.

Pretty-print a path, including the leading /.

A representation of the request body(s) that a Servant endpoint expects.

Under the hood, Request is a Some TypeRep. This allows for the possibility that an endpoint might expect the request body to parse as several different types (multiple ReqBody's).

Note that this type doesn't include any information about the headers that an endpoint expects, since those are independent of the request body.

The endpoint doesn't expect a request body.

The request body can only be of one type. Equivalent to a single ReqBody _ a.

The endpoint expects the request body to be parsed as multiple (>1) types. Equivalent to multiple ReqBodys chained with :>.

A representation of one possible response that a Servant endpoint can return.

Currently, the only situation in which multiple Responses can be returned is using the UVerb combinator. This bundles response types together with response Headers, so we do the same here.

A representation of the response(s) that a Servant endpoint can return.

Under the hood, Responses is a Some Response. This allows for the possibility that an endpoint might return one of several responses, via UVerb.

Note that a Response consists of a return body type, as well as the return headers.

The endpoint will not return a response.

There is only one possible response. Equivalent to a single ReqBody _ a.

The endpoint may return one of multiple multiple (>1) responses. Equivalent to a UVerbs with more than one type.

Simple term-level representation of a Header.

A type-level Header (sym :: Symbol) typ should correspond to HeaderRep { _hName = str, _hType = typRep }, where str is the term-level equivalent of sym and typRep is the term-level representation of typ.

Convenience function to construct a HeaderRep from sym :: Symbol and a :: Type'.

Newtype wrapper around servant's Param so we can define a sensible Eq instance for it.

Create a SingleParam from a Symbol and a TypeRep via Typeable.

Create an ArrayParam from a Symbol and a TypeRep via Typeable.

Create a FlagParam from a Symbol.

Pretty-print a Param. Used by renderRoute.

There are 2 variants:

• "Basic" authentication: corresponds to the BasicAuth type. Construct with basicAuth.
• "Custom" authentication: corresponds to the AuthProtect type. Construct with customAuth.

Create a term-level representation of a "Basic" authentication scheme.

For example:

ghci> toJSON $ basicAuth @"user"
String "Basic user"

Create a term-level representation of a "Custom" authentication scheme, i.e. one that corresponds to Servant's AuthProtect combinator.

For example:

ghci> toJSON $ customAuth @"OnlyAdminUsers"
String "OnlyAdminUsers"