servant-0.20.2: A family of combinators for defining webservices APIs

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 :: [Type]) (as :: [Type])
- class KnownStatus (StatusOf a) => HasStatus (a :: Type) where
  - type StatusOf (a :: Type) :: Nat
- statusOf :: forall a proxy. HasStatus a => proxy a -> Status
- class HasStatuses (as :: [Type]) where
  - type Statuses (as :: [Type]) :: [Nat]
  - statuses :: Proxy as -> [Status]
- newtype WithStatus (k :: Nat) a = WithStatus a
- module Servant.API.UVerb.Union

# Documentation

data UVerb (method :: StdMethod) (contentTypes :: [Type]) (as :: [Type]) 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 #
AtMostOneFragment (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 :: Type) Source #

Associated Types

type StatusOf (a :: Type) :: 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 :: [Type]) where Source #

Associated Types

type Statuses (as :: [Type]) :: [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 Source # show :: WithStatus k a -> String Source # showList :: [WithStatus k a] -> ShowS Source #
Eq a => Eq (WithStatus k a) Source # |
Instance details Defined in Servant.API.UVerb Methods (==) :: WithStatus k a -> WithStatus k a -> Bool Source # (/=) :: WithStatus k a -> WithStatus k a -> Bool 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 #
type StatusOf (WithStatus n a) Source # |
Instance details Defined in Servant.API.UVerb type StatusOf (WithStatus n a) = n

module Servant.API.UVerb.Union