Moduleservant-0.20.2Haskell2010

Servant.API.UVerb

An alternative to Verb for end-points that respond with a resource value of any of an open union of types, and specific status codes for each type in this union. (UVerb is short for UnionVerb)

This can be used for returning (rather than throwing) exceptions in a server as in, say '[Report, WaiError]; or responding with either a 303 forward with a location header, or 201 created with a different body type, depending on the circumstances. (All of this can be done with vanilla servant-server by throwing exceptions, but it can't be represented in the API types without something like UVerb.)

See https://docs.servant.dev/en/stable/cookbook/uverb/UVerb.html for a working example.

2 types
2 classes
1 value

Packageservant-0.20.2
Exports5
LanguageHaskell2010
LicenceBSD-3-Clause
SourceUVerb.hs

datadata UVerb (method :: StdMethod) (contentTypes :: [Type]) (as :: [Type])

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.

Instances3HasLink, AtMostOneFragment, MkLink

HasLink (UVerb m ct a)Defined in servant-0.20.2 · Servant.Links
AtMostOneFragment (UVerb m cts as)Defined in servant-0.20.2 · Servant.API.TypeLevel
type MkLink (UVerb m ct a) r = rDefined in servant-0.20.2 · Servant.Links

classclass KnownStatus (StatusOf a) => HasStatus a where

Associated types

type family StatusOf a :: Nat

Instances3HasStatus

HasStatus NoContentDefined in servant-0.20.2 · Servant.API.UVerb
If an API can respond with NoContent we assume that this will happen with the status code 204 No Content. If this needs to be overridden, WithStatus can be used.
KnownStatus n => HasStatus (WithStatus n a)Defined in servant-0.20.2 · Servant.API.UVerb
an instance of this typeclass assigns a HTTP status code to a return type
Example:
```
   data NotFoundError = NotFoundError String

   instance HasStatus NotFoundError where
     type StatusOf NotFoundError = 404
```
You can also use the convience newtype wrapper WithStatus if you want to avoid writing a HasStatus instance manually. It also has the benefit of showing the status code in the type; which might aid in readability.
HasStatus a => HasStatus (Headers ls a)Defined in servant-0.20.2 · Servant.API.UVerb

valuestatusOf :: HasStatus a => proxy a -> Status

classclass HasStatuses (as :: [Type]) where

Associated types

type family Statuses (as :: [Type]) :: [Nat]

Methods

statuses :: Proxy as -> [Status]

Instances2HasStatuses

HasStatuses '[]Defined in servant-0.20.2 · Servant.API.UVerb
(HasStatus a, HasStatuses as) => HasStatuses (a ': as)Defined in servant-0.20.2 · Servant.API.UVerb

newtypenewtype WithStatus (k :: Nat) a

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

Constructors

WithStatus a

Instances12MimeRender, MimeUnrender, Eq, Show, HasStatus, StatusOf, …

MimeRender FormUrlEncoded a => MimeRender FormUrlEncoded (WithStatus _status a)Defined in servant-0.20.2 · Servant.API.UVerb
MimeRender JSON a => MimeRender JSON (WithStatus _status a)Defined in servant-0.20.2 · Servant.API.UVerb
MimeRender OctetStream a => MimeRender OctetStream (WithStatus _status a)Defined in servant-0.20.2 · Servant.API.UVerb
MimeRender PlainText a => MimeRender PlainText (WithStatus _status a)Defined in servant-0.20.2 · Servant.API.UVerb
MimeUnrender FormUrlEncoded a => MimeUnrender FormUrlEncoded (WithStatus _status a)Defined in servant-0.20.2 · Servant.API.UVerb
MimeUnrender JSON a => MimeUnrender JSON (WithStatus _status a)Defined in servant-0.20.2 · Servant.API.UVerb
MimeUnrender OctetStream a => MimeUnrender OctetStream (WithStatus _status a)Defined in servant-0.20.2 · Servant.API.UVerb
MimeUnrender PlainText a => MimeUnrender PlainText (WithStatus _status a)Defined in servant-0.20.2 · Servant.API.UVerb
Eq a => Eq (WithStatus k a)Defined in servant-0.20.2 · Servant.API.UVerb
Show a => Show (WithStatus k a)Defined in servant-0.20.2 · Servant.API.UVerb
KnownStatus n => HasStatus (WithStatus n a)Defined in servant-0.20.2 · Servant.API.UVerb
an instance of this typeclass assigns a HTTP status code to a return type
Example:
```
   data NotFoundError = NotFoundError String

   instance HasStatus NotFoundError where
     type StatusOf NotFoundError = 404
```
You can also use the convience newtype wrapper WithStatus if you want to avoid writing a HasStatus instance manually. It also has the benefit of showing the status code in the type; which might aid in readability.
type StatusOf (WithStatus n a) = nDefined in servant-0.20.2 · Servant.API.UVerb

module Servant.API.UVerb.Union