Servant.API

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

Optional argument. Wrapped in Maybe.

Required argument. Not wrapped.

Strictly parsed argument. Not wrapped.

Extract the whole query string from a request. This is useful for query strings containing dynamic parameter names. For query strings with static parameter names, QueryParam is more suited.

Example:

>>> -- /books?author=<author name>&year=<book year>>>> type MyApi = "books" :> QueryString :> Get '[JSON] [Book]

Extract an deep object from a query string.

Example:

>>> -- /books?filter[author][name]=<author name>&filter[year]=<book year>>>> type MyApi = "books" :> DeepQuery "filter" BookQuery :> Get '[JSON] [Book]

DELETE with 200 status code.

DELETE with 202 status code.

DELETE with 204 status code.

DELETE with 203 status code.

GET with 200 status code.

GET with 202 status code.

GET with 204 status code.

GET with 203 status code.

GET with 206 status code.

GET with 205 status code.

NoContentVerb is a specific type to represent NoContent responses. It does not require either a list of content types (because there's no content) or a status code (because it should always be 204).

PATCH with 200 status code.

PATCH with 202 status code.

PATCH with 204 status code.

PATCH with 203 status code.

POST with 200 status code.

POST with 202 status code.

POST with 201 status code.

POST with 204 status code.

POST with 203 status code.

POST with 205 status code.

PUT with 200 status code.

PUT with 202 status code.

PUT with 201 status code.

PUT with 204 status code.

PUT with 203 status code.

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

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

A variant of Verb that can have any of a number of response values and status codes.

FUTUREWORK: it would be nice to make Verb a special case of UVerb, and only write instances for HasServer etc. for the latter, getting them for the former for free. Something like:

type Verb method statusCode contentTypes a = UVerb method contentTypes [WithStatus statusCode a]

Backwards compatibility is tricky, though: this type alias would mean people would have to use respond instead of pure or return, so all old handlers would have to be rewritten.

Check whether all values in a type-level list are distinct. This will throw a nice error if there are any duplicate elements in the list.

A simple newtype wrapper that pairs a type with its status code. It implements all the content types that Servant ships with by default.

A type that specifies that an API record contains an API definition. Only useful at type-level.

A class with a type family that applies an appropriate type family to the api parameter. For example, AsApi will leave api untouched, while AsServerT m will produce ServerT api m.

A constraint alias, for work with mode and routes.

Turns a generic product type into a tree of :<|> combinators.

Inverse of toServant.

This can be used to turn generated values such as client functions into records.

You may need to provide a type signature for the output type (your record type).

Get a Proxy of an API type.

See ToServant, but at value-level.

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.

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.

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

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.

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

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.

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.

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 String 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

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"):}

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

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

A type for responses without content-body.

Response Header objects. You should never need to construct one directly. Instead, use addOptionalHeader.

addHeader adds a header to a response. Note that it changes the type of the value in the following ways:

1. A simple value is wrapped in "Headers '[hdr]":

>>> let example0 = addHeader 5 "hi" :: Headers '[Header "someheader" Int] String;>>> getHeaders example0[("someheader","5")]

2. A value that already has a header has its new header *prepended* to the existing list:

>>> let example1 = addHeader 5 "hi" :: Headers '[Header "someheader" Int] String;>>> let example2 = addHeader True example1 :: Headers '[Header "1st" Bool, Header "someheader" Int] String>>> getHeaders example2[("1st","true"),("someheader","5")]

Note that while in your handlers type annotations are not required, since the type can be inferred from the API type, in other cases you may find yourself needing to add annotations.

Same as addHeader but works with Header', so it's possible to use any mods.

Look up a specific ResponseHeader, without having to know what position it is in the HList.

>>> let example1 = addHeader 5 "hi" :: Headers '[Header "someheader" Int] String>>> let example2 = addHeader True example1 :: Headers '[Header "1st" Bool, Header "someheader" Int] String>>> lookupResponseHeader example2 :: ResponseHeader "someheader" IntHeader 5

>>> lookupResponseHeader example2 :: ResponseHeader "1st" BoolHeader True

Usage of this function relies on an explicit type annotation of the header to be looked up. This can be done with type annotations on the result, or with an explicit type application. In this example, the type of header value is determined by the type-inference, we only specify the name of the header:

>>> :set -XTypeApplications>>> case lookupResponseHeader @"1st" example2 of { Header b -> b ; _ -> False }True

Deliberately do not add a header to a value.

>>> let example1 = noHeader "hi" :: Headers '[Header "someheader" Int] String>>> getHeaders example1[]

Same as noHeader but works with Header', so it's possible to use any mods.

Parse value from HTTP API data.

WARNING: Do not derive this using DeriveAnyClass as the generated instance will loop indefinitely.

Convert value to HTTP API data.

WARNING: Do not derive this using DeriveAnyClass as the generated instance will loop indefinitely.

Construct a toLink for an endpoint.

Closed type family, check if endpoint is within api. Uses IsElem' if it exhausts all other options.

>>> ok (Proxy :: Proxy (IsElem ("hello" :> Get '[JSON] Int) SampleAPI))OK

>>> ok (Proxy :: Proxy (IsElem ("bye" :> Get '[JSON] Int) SampleAPI))...... Could not ......

An endpoint is considered within an api even if it is missing combinators that don't affect the URL:

>>> ok (Proxy :: Proxy (IsElem (Get '[JSON] Int) (Header "h" Bool :> Get '[JSON] Int)))OK

>>> ok (Proxy :: Proxy (IsElem (Get '[JSON] Int) (ReqBody '[JSON] Bool :> Get '[JSON] Int)))OK

• N.B.:* IsElem a b can be seen as capturing the notion of whether the URL represented by a would match the URL represented by b, *not* whether a request represented by a matches the endpoints serving b (for the latter, use IsIn).

You may use this type family to tell the type checker that your custom type may be skipped as part of a link. This is useful for things like QueryParam that are optional in a URI and do not affect them if they are omitted.

>>> data CustomThing>>> type instance IsElem' e (CustomThing :> s) = IsElem e s

Note that IsElem is called, which will mutually recurse back to IsElem' if it exhausts all other options again.

Once you have written a HasLink instance for CustomThing you are ready to go.

A safe link datatype. The only way of constructing a Link is using safeLink, which means any Link is guaranteed to be part of the mentioned API.

Represents a general universal resource identifier using its component parts.

For example, for the URI

  foo://anonymous@www.haskell.org:42/ghc?query#frag

the components are:

Create a valid (by construction) relative URI with query params.

This function will only typecheck if endpoint is part of the API api

Type-level If. If True a b ==> a; If False a b ==> b