Servant.Foreign.Internal

Canonical name of the endpoint, can be used to generate a function name.

You can use the functions in Servant.Foreign.Inflections, like camelCase to transform to Text.

See documentation of Arg

Maps a name to the foreign type that belongs to the annotated value.

Used for header args, query args, and capture args.

A part of the Url’s path.

Whether a segment is a Cap.

Crashing Arg extraction from segment, TODO: remove

Type of a QueryArg.

Url Query argument.

Urls can contain query arguments, which is a list of key-value pairs. In a typical url, query arguments look like this:

?foo=bar&alist[]=el1&alist[]=el2&aflag

Each pair can be

• ?foo=bar: a plain key-val pair, either optional or required (QueryParam)

• ?aflag: a flag (no value, implicitly Bool with default false if it’s missing) (QueryFlag)

• ?alist[]=el1&alist[]=el2: list of values (QueryParams)

_queryArgType will be set accordingly.

For the plain key-val pairs (QueryParam), _queryArgName’s ftype will be wrapped in a Maybe if the argument is optional.

Full endpoint url, with all captures and parameters

See documentation of _reqBodyContentType

Full description of an endpoint in your API, generated by listFromAPI. It should give you all the information needed to generate foreign language bindings.

Every field containing ftype will use the foreign type mapping specified via HasForeignType (see its docstring on how to set that up).

See https://docs.servant.dev/en/stable/tutorial/ApiType.html for accessible documentation of the possible content of an endpoint.

HasForeignType maps Haskell types with types in the target language of your backend. For example, let's say you're implementing a backend to some language X, and you want a Text representation of each input/output type mentioned in the API:

-- First you need to create a dummy type to parametrize your
-- instances.
data LangX

-- Otherwise you define instances for the types you need
instance HasForeignType LangX Text Int where
   typeFor _ _ _ = "intX"

-- Or for example in case of lists
instance HasForeignType LangX Text a => HasForeignType LangX Text [a] where
   typeFor lang ftype _ = "listX of " <> typeFor lang ftype (Proxy :: Proxy a)

Finally to generate list of information about all the endpoints for an API you create a function of a form:

getEndpoints :: (HasForeign LangX Text api, GenerateList Text (Foreign Text api))
             => Proxy api -> [Req Text]
getEndpoints api = listFromAPI (Proxy :: Proxy LangX) (Proxy :: Proxy Text) api

-- If language __X__ is dynamically typed then you can use
-- a predefined NoTypes parameter with the NoContent output type:

getEndpoints :: (HasForeign NoTypes NoContent api, GenerateList Text (Foreign NoContent api))
             => Proxy api -> [Req NoContent]
getEndpoints api = listFromAPI (Proxy :: Proxy NoTypes) (Proxy :: Proxy NoContent) api

The language definition without any foreign types. It can be used for dynamic languages which do not do type annotations.

Implementation of the Servant framework types.

Relevant instances: Everything containing HasForeignType.

Utility class used by listFromAPI which computes the data needed to generate a function for each endpoint and hands it all back in a list.

Generate the necessary data for codegen as a list, each Req describing one endpoint from your API type.