Safe Haskell	Safe-Inferred
Language	Haskell2010

Servant.API.UVerb

Description

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.

Synopsis

data UVerb (method :: StdMethod) (contentTypes :: [*]) (as :: [*])
class KnownStatus (StatusOf a) => HasStatus (a :: *) where
- type StatusOf (a :: *) :: Nat
statusOf :: forall a proxy. HasStatus a => proxy a -> Status
class HasStatuses (as :: [*]) where
- type Statuses (as :: [*]) :: [Nat]
- statuses :: Proxy as -> [Status]
newtype WithStatus (k :: Nat) a = WithStatus a
module Servant.API.UVerb.Union

Documentation

data UVerb (method :: StdMethod) (contentTypes :: [*]) (as :: [*]) Source #

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.

Instances

Instances details

HasLink (UVerb m ct a :: Type) Source #
Instance details Defined in Servant.Links Associated Types type MkLink (UVerb m ct a) a Source # Methods toLink :: (Link -> a0) -> Proxy (UVerb m ct a) -> Link -> MkLink (UVerb m ct a) a0 Source #
AtLeastOneFragment (UVerb m cts as) Source #
Instance details Defined in Servant.API.TypeLevel
type MkLink (UVerb m ct a :: Type) r Source #
Instance details Defined in Servant.Links type MkLink (UVerb m ct a :: Type) r = r

class KnownStatus (StatusOf a) => HasStatus (a :: *) Source #

Associated Types

type StatusOf (a :: *) :: Nat Source #

Instances

Instances details

HasStatus NoContent Source #	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.
Instance details Defined in Servant.API.UVerb Associated Types type StatusOf NoContent :: Nat Source #
HasStatus a => HasStatus (Headers ls a) Source #
Instance details Defined in Servant.API.UVerb Associated Types type StatusOf (Headers ls a) :: Nat Source #
KnownStatus n => HasStatus (WithStatus n a) Source #	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.
Instance details Defined in Servant.API.UVerb Associated Types type StatusOf (WithStatus n a) :: Nat Source #

statusOf :: forall a proxy. HasStatus a => proxy a -> Status Source #

class HasStatuses (as :: [*]) where Source #

Associated Types

type Statuses (as :: [*]) :: [Nat] Source #

Methods

statuses :: Proxy as -> [Status] Source #

Instances

Instances details

HasStatuses ('[] :: [Type]) Source #
Instance details Defined in Servant.API.UVerb Associated Types type Statuses '[] :: [Nat] Source # Methods statuses :: Proxy '[] -> [Status] Source #
(HasStatus a, HasStatuses as) => HasStatuses (a ': as) Source #
Instance details Defined in Servant.API.UVerb Associated Types type Statuses (a ': as) :: [Nat] Source # Methods statuses :: Proxy (a ': as) -> [Status] Source #

newtype WithStatus (k :: Nat) a Source #

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

Instances

Instances details

MimeRender FormUrlEncoded a => MimeRender FormUrlEncoded (WithStatus _status a) Source #
Instance details Defined in Servant.API.UVerb Methods mimeRender :: Proxy FormUrlEncoded -> WithStatus _status a -> ByteString Source #
MimeRender JSON a => MimeRender JSON (WithStatus _status a) Source #
Instance details Defined in Servant.API.UVerb Methods mimeRender :: Proxy JSON -> WithStatus _status a -> ByteString Source #
MimeRender OctetStream a => MimeRender OctetStream (WithStatus _status a) Source #
Instance details Defined in Servant.API.UVerb Methods mimeRender :: Proxy OctetStream -> WithStatus _status a -> ByteString Source #
MimeRender PlainText a => MimeRender PlainText (WithStatus _status a) Source #
Instance details Defined in Servant.API.UVerb Methods mimeRender :: Proxy PlainText -> WithStatus _status a -> ByteString Source #
MimeUnrender FormUrlEncoded a => MimeUnrender FormUrlEncoded (WithStatus _status a) Source #
Instance details Defined in Servant.API.UVerb Methods mimeUnrender :: Proxy FormUrlEncoded -> ByteString -> Either String (WithStatus _status a) Source # mimeUnrenderWithType :: Proxy FormUrlEncoded -> MediaType -> ByteString -> Either String (WithStatus _status a) Source #
MimeUnrender JSON a => MimeUnrender JSON (WithStatus _status a) Source #
Instance details Defined in Servant.API.UVerb Methods mimeUnrender :: Proxy JSON -> ByteString -> Either String (WithStatus _status a) Source # mimeUnrenderWithType :: Proxy JSON -> MediaType -> ByteString -> Either String (WithStatus _status a) Source #
MimeUnrender OctetStream a => MimeUnrender OctetStream (WithStatus _status a) Source #
Instance details Defined in Servant.API.UVerb Methods mimeUnrender :: Proxy OctetStream -> ByteString -> Either String (WithStatus _status a) Source # mimeUnrenderWithType :: Proxy OctetStream -> MediaType -> ByteString -> Either String (WithStatus _status a) Source #
MimeUnrender PlainText a => MimeUnrender PlainText (WithStatus _status a) Source #
Instance details Defined in Servant.API.UVerb Methods mimeUnrender :: Proxy PlainText -> ByteString -> Either String (WithStatus _status a) Source # mimeUnrenderWithType :: Proxy PlainText -> MediaType -> ByteString -> Either String (WithStatus _status a) Source #
Show a => Show (WithStatus k a) Source #
Instance details Defined in Servant.API.UVerb Methods showsPrec :: Int -> WithStatus k a -> ShowS # show :: WithStatus k a -> String # showList :: [WithStatus k a] -> ShowS #
Eq a => Eq (WithStatus k a) Source #
Instance details Defined in Servant.API.UVerb Methods (==) :: WithStatus k a -> WithStatus k a -> Bool # (/=) :: WithStatus k a -> WithStatus k a -> Bool #
KnownStatus n => HasStatus (WithStatus n a) Source #	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.
Instance details Defined in Servant.API.UVerb Associated Types type StatusOf (WithStatus n a) :: Nat Source #
type StatusOf (WithStatus n a) Source #
Instance details Defined in Servant.API.UVerb type StatusOf (WithStatus n a) = n

module Servant.API.UVerb.Union