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

Safe Haskell | None
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 where
  - type StatusOf a :: Nat
- statusOf :: 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]) #

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) # |
Instance details Defined in Servant.Links Methods toLink :: (Link -> a0) -> Proxy (UVerb m ct a) -> Link -> MkLink (UVerb m ct a) a0 #
AtMostOneFragment (UVerb m cts as) # |
Instance details Defined in Servant.API.TypeLevel
type MkLink (UVerb m ct a :: Type) r # |
Instance details Defined in Servant.Links type MkLink (UVerb m ct a :: Type) r = r

class KnownStatus (StatusOf a) => HasStatus a #

Associated Types

type StatusOf a :: Nat #

#### Instances

Instances details

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

statusOf :: HasStatus a => proxy a -> Status #

class HasStatuses (as :: [Type]) where #

Associated Types

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

Methods

statuses :: Proxy as -> [Status] #

#### Instances

Instances details

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

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

#### Instances

Instances details

MimeRender FormUrlEncoded a => MimeRender FormUrlEncoded (WithStatus _status a) # |
Instance details Defined in Servant.API.UVerb Methods mimeRender :: Proxy FormUrlEncoded -> WithStatus _status a -> ByteString #
MimeRender JSON a => MimeRender JSON (WithStatus _status a) # |
Instance details Defined in Servant.API.UVerb Methods mimeRender :: Proxy JSON -> WithStatus _status a -> ByteString #
MimeRender OctetStream a => MimeRender OctetStream (WithStatus _status a) # |
Instance details Defined in Servant.API.UVerb Methods mimeRender :: Proxy OctetStream -> WithStatus _status a -> ByteString #
MimeRender PlainText a => MimeRender PlainText (WithStatus _status a) # |
Instance details Defined in Servant.API.UVerb Methods mimeRender :: Proxy PlainText -> WithStatus _status a -> ByteString #
MimeUnrender FormUrlEncoded a => MimeUnrender FormUrlEncoded (WithStatus _status a) # |
Instance details Defined in Servant.API.UVerb Methods mimeUnrender :: Proxy FormUrlEncoded -> ByteString -> Either String (WithStatus _status a) # mimeUnrenderWithType :: Proxy FormUrlEncoded -> MediaType -> ByteString -> Either String (WithStatus _status a) #
MimeUnrender JSON a => MimeUnrender JSON (WithStatus _status a) # |
Instance details Defined in Servant.API.UVerb Methods mimeUnrender :: Proxy JSON -> ByteString -> Either String (WithStatus _status a) # mimeUnrenderWithType :: Proxy JSON -> MediaType -> ByteString -> Either String (WithStatus _status a) #
MimeUnrender OctetStream a => MimeUnrender OctetStream (WithStatus _status a) # |
Instance details Defined in Servant.API.UVerb Methods mimeUnrender :: Proxy OctetStream -> ByteString -> Either String (WithStatus _status a) # mimeUnrenderWithType :: Proxy OctetStream -> MediaType -> ByteString -> Either String (WithStatus _status a) #
MimeUnrender PlainText a => MimeUnrender PlainText (WithStatus _status a) # |
Instance details Defined in Servant.API.UVerb Methods mimeUnrender :: Proxy PlainText -> ByteString -> Either String (WithStatus _status a) # mimeUnrenderWithType :: Proxy PlainText -> MediaType -> ByteString -> Either String (WithStatus _status a) #
Show a => Show (WithStatus k a) # |
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) # |
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) # | 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) |
Instance details Defined in Servant.API.UVerb type StatusOf (WithStatus n a) = n
type StatusOf (WithStatus n a) # |
Instance details Defined in Servant.API.UVerb type StatusOf (WithStatus n a) = n

module Servant.API.UVerb.Union