The contained API (second argument) can be found under ("/" ++ path) (path being the first argument).

Example:

>>> -- GET /hello/world
>>> -- returning a JSON encoded World value
>>> type MyApi = "hello" :> "world" :> Get '[JSON] World

Union of two APIs, first takes precedence in case of overlap.

Example:

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

An empty API: one which serves nothing. Morally speaking, this should be the unit of :<|>. Implementors of interpretations of API types should treat EmptyAPI as close to the unit as possible.

Strictly parsed argument. Not wrapped.

Leniently parsed argument, i.e. parsing never fail. Wrapped in Either Text.

Optional argument. Wrapped in Maybe.

Required argument. Not wrapped.

Capture all remaining values from the request path under a certain type a.

Example:

>>> -- GET /src/*
>>> type MyAPI = "src" :> CaptureAll "segments" Text :> Get '[JSON] SourceFile

Capture which can be modified. For example with Description.

Capture a value from the request path under a certain type a.

Example:

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

Extract the given header's value as a value of type a. I.e. header sent by client, parsed by server.

Example:

>>> newtype Referer = Referer Text deriving (Eq, Show)
>>> 
>>> -- GET /view-my-referer
>>> type MyApi = "view-my-referer" :> Header "from" Referer :> Get '[JSON] Referer

HTTP Version.

Note that the Show instance is intended merely for debugging.

Lookup a potentially value-less query string parameter with boolean semantics. If the param sym is there without any value, or if it's there with value "true" or "1", it's interpreted as True. Otherwise, it's interpreted as False.

Example:

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

Lookup the values associated to the sym query string parameter and try to extract it as a value of type [a]. This is typically meant to support query string parameters of the form param[]=val1&param[]=val2 and so on. Note that servant doesn't actually require the []s and will fetch the values just fine with param=val1&param=val2, too.

Example:

>>> -- /books?authors[]=<author1>&authors[]=<author2>&...
>>> type MyApi = "books" :> QueryParams "authors" Text :> Get '[JSON] [Book]

QueryParam which can be Required, Lenient, or modified otherwise.

Lookup the value associated to the sym query string parameter and try to extract it as a value of type a.

Example:

>>> -- /books?author=<author name>
>>> type MyApi = "books" :> QueryParam "author" Text :> Get '[JSON] [Book]

Note: ReqBody' is always Required.

Extract the request body as a value of type a.

Example:

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

Provides access to the host or IP address from which the HTTP request was sent.

Was this request made over an SSL connection?

Note that this value will not tell you if the client originally made this request over SSL, but rather whether the current connection is SSL. The distinction lies with reverse proxies. In many cases, the client will connect to a load balancer over SSL, but connect to the WAI handler without SSL. In such a case, the handlers would get NotSecure, but from a user perspective, there is a secure connection.

A persistent store for values of arbitrary types.

This variant is the simplest and creates keys in the IO monad. See the module Data.Vault.ST if you want to use it with the ST monad instead.

WithNamedContext names a specific tagged context to use for the combinators in the API. (See also in servant-server, Servant.Server.Context.) For example:

type UseNamedContextAPI = WithNamedContext "myContext" '[String] (
    ReqBody '[JSON] Int :> Get '[JSON] Int)

Both the ReqBody and Get combinators will use the WithNamedContext with type tag "myContext" as their context.

Contexts are only relevant for servant-server.

For more information, see the tutorial.

HTTP standard method (as defined by RFC 2616, and PATCH which is defined by RFC 5789).

GET with 206 status code.

POST with 205 status code.

GET with 205 status code.

PUT with 204 status code.

PATCH with 204 status code.

DELETE with 204 status code.

POST with 204 status code.

GET with 204 status code.

PUT with 203 status code.

PATCH with 203 status code.

DELETE with 203 status code.

POST with 203 status code.

GET with 203 status code.

PUT with 202 status code.

PATCH with 202 status code.

DELETE with 202 status code.

POST with 202 status code.

GET with 202 status code.

PUT with 201 status code.

POST with 201 status code.

PATCH with 200 status code.

DELETE with 200 status code.

PUT with 200 status code.

POST with 200 status code.

GET with 200 status code.

Verb is a general type for representing HTTP verbs (a.k.a. methods). For convenience, type synonyms for each verb with a 200 response code are provided, but you are free to define your own:

>>> type Post204 contentTypes a = Verb 'POST 204 contentTypes a

The netstring framing strategy as defined by djb: http://cr.yp.to/proto/netstrings.txt

Any string of 8-bit bytes may be encoded as [len]":"[string]",". Here [string] is the string and [len] is a nonempty sequence of ASCII digits giving the length of [string] in decimal. The ASCII digits are 30 for 0, 31 for 1, and so on up through 39 for 9. Extra zeros at the front of [len] are prohibited: [len] begins with 30 exactly when [string] is empty.

For example, the string "hello world!" is encoded as 32 3a 68 65 6c 6c 6f 20 77 6f 72 6c 64 21 2c, i.e., "12:hello world!,". The empty string is encoded as "0:,".

A simple framing strategy that has no header, and inserts a newline character after each frame. This assumes that it is used with a Content-Type that encodes without newlines (e.g. JSON).

A framing strategy that does not do any framing at all, it just passes the input data This will be used most of the time with binary data, such as files

The FramingUnrender class provides the logic for parsing a framing strategy.

The FramingRender class provides the logic for emitting a framing strategy. The strategy transforms a SourceT m a into SourceT m ByteString, therefore it can prepend, append and intercalate framing structure around chunks.

Note: as the Monad m is generic, this is pure transformation.

FromSourceIO is intended to be implemented for types such as Conduit, Pipe, etc. By implementing this class, all such streaming abstractions can be used directly on the client side for talking to streaming endpoints.

ToSourceIO is intended to be implemented for types such as Conduit, Pipe, etc. By implementing this class, all such streaming abstractions can be used directly as endpoints.

Stream endpoints may be implemented as producing a SourceIO chunk.

Clients reading from streaming endpoints can be implemented as consuming a SourceIO chunk.

A stream request body.

A Stream endpoint for a given method emits a stream of encoded values at a given Content-Type, delimited by a framing strategy. Type synonyms are provided for standard methods.

A simple datatype to hold data required to decorate a request

Combinator for Basic Access Authentication.

• IMPORTANT*: Only use Basic Auth over HTTPS! Credentials are not hashed or encrypted. Note also that because the same credentials are sent on every request, Basic Auth is not as secure as some alternatives. Further, the implementation in servant-server does not protect against some types of timing attacks.

In Basic Auth, username and password are base64-encoded and transmitted via the Authorization header. Handshakes are not required, making it relatively efficient.

Add more verbose description for (part of) API.

Example:

>>> :{
type MyApi = Description
 "This comment is visible in multiple Servant interpretations \
 \and can be really long if necessary. \
 \Haskell multiline support is not perfect \
 \but it's still very readable."
:> Get '[JSON] Book
:}

Add a short summary for (part of) API.

Example:

>>> type MyApi = Summary "Get book by ISBN." :> "books" :> Capture "isbn" Text :> Get '[JSON] Book

A type for responses without content-body.

Instantiate this class to register a way of deserializing a type based on the request's Content-Type header.

>>> import Network.HTTP.Media hiding (Accept)
>>> import qualified Data.ByteString.Lazy.Char8 as BSC
>>> data MyContentType = MyContentType String

>>> :{
instance Accept MyContentType where
   contentType _ = "example" // "prs.me.mine" /: ("charset", "utf-8")
:}

>>> :{
instance Read a => MimeUnrender MyContentType a where
   mimeUnrender _ bs = case BSC.take 12 bs of
     "MyContentType" -> return . read . BSC.unpack $ BSC.drop 12 bs
     _ -> Left "didn't start with the magic incantation"
:}

>>> type MyAPI = "path" :> ReqBody '[MyContentType] Int :> Get '[JSON] Int

Instantiate this class to register a way of serializing a type based on the Accept header.

Example:

data MyContentType

instance Accept MyContentType where
   contentType _ = "example" // "prs.me.mine" /: ("charset", "utf-8")

instance Show a => MimeRender MyContentType a where
   mimeRender _ val = pack ("This is MINE! " ++ show val)

type MyAPI = "path" :> Get '[MyContentType] Int

Instances of Accept represent mimetypes. They are used for matching against the Accept HTTP header of the request, and for setting the Content-Type header of the response

Example:

>>> import Network.HTTP.Media ((//), (/:))
>>> data HTML
>>> :{
instance Accept HTML where
   contentType _ = "text" // "html" /: ("charset", "utf-8")
:}