Servant.API.MultiVerb

MultiVerb produces an endpoint which can return multiple values with various content types and status codes. It is similar to UVerb and behaves similarly, but it has some important differences:

• Descriptions and statuses can be attached to individual responses without using wrapper types and without affecting the handler return type.

• The return type of the handler can be decoupled from the types of the individual responses. One can use a Union type just like for UVerb, but MultiVerb also supports using an arbitrary type with an AsUnion instance. Each response is responsible for their content type.

• Headers can be attached to individual responses, also without affecting the handler return type.

Example

Let us create an endpoint that captures an Int and has the following logic:

• If the number is negative, we return status code 400 and an empty body;

• If the number is even, we return a Bool in the response body;

• If the number is odd, we return another Int in the response body.

 import qualified Generics.SOP as GSOP

-- All possible HTTP responses
type Responses =
  '[ type RespondEmpty 400 "Negative"
   , type Respond 200 "Even number" Bool
   , type Respond 200 "Odd number" Int
   ]

-- All possible return types
data Result
  = NegativeNumber
  | Odd Int
  | Even Bool
  deriving stock (Generic)
  deriving (AsUnion Responses)
    via GenericAsUnion Responses Result

instance GSOP.Generic Result

These deriving statements above tie together the responses and the return values, and the order in which they are defined matters. For instance, if Even and Odd had switched places in the definition of Result, this would provoke an error:

• No instance for ‘AsConstructor
    ((:) @Type Int ('[] @Type)) (Respond 200 "Even number" Bool)’
        arising from the 'deriving' clause of a data type declaration

If you would prefer to write an intance of AsUnion by yourself, read more in the typeclass' documentation.

Finally, let us write our endpoint description:

type MultipleChoicesInt =
  Capture "int" Int
  :> MultiVerb
    'GET
    '[JSON]
    Responses
    Result

A MultiVerb endpoint with a single response. Ideal to ensure that there can only be one response.

A type to describe a MultiVerb response.

Includes status code, description, and return type. The content type of the response is determined dynamically using the accept header and the list of supported content types specified in the containing MultiVerb type.

A type to describe a MultiVerb response with a fixed content type.

Similar to Respond, but hardcodes the content type to be used for generating the response. This content type is distinct from the one given to MultiVerb, as it dictactes the response's content type, not the content type request that is to be accepted.

A type to describe a MultiVerb response with an empty body.

Includes status code and description.

A type to describe a streaming MultiVerb response.

Includes status code, description, framing strategy and content type. Note that the handler return type is hardcoded to be 'SourceIO ByteString'.

This type adds response headers to a MultiVerb response.

A wrapper to turn a response header into an optional one.

This is used to convert a response containing headers to a custom type including the information in the headers.

If you need to send a combination of headers and response that is not provided by Servant, you can cwrite your own instance. Take example on the ones provided.

This class is used to convert a handler return type to a union type including all possible responses of a MultiVerb endpoint.

Any glue code necessary to convert application types to and from the canonical Union type corresponding to a MultiVerb endpoint should be packaged into an AsUnion instance.

Example

Let us take the example endpoint from the MultiVerb documentation. There, we derived the AsUnion instance with the help of Generics. The manual way of implementing the instance is:

instance AsUnion Responses Result where
  toUnion NegativeNumber = Z (I ())
  toUnion (Even b) = S (Z (I b))
  toUnion (Odd i) = S (S (Z (I i)))

  fromUnion       (Z (I ())) = NegativeNumber
  fromUnion    (S (Z (I b))) = Even b
  fromUnion (S (S (Z (I i)))) = Odd i
  fromUnion (S (S (S x))) = case x of {}

The last fromUnion equation is here to please the pattern checker.

This class can be instantiated to get automatic derivation of AsUnion instances via GenericAsUnion. The idea is that one has to make sure that for each response r in a MultiVerb endpoint, there is an instance of AsConstructor xs r for some xs, and that the list xss of all the corresponding xs is equal to Code of the handler type. Then one can write: @ type Responses = ... data Result = ... deriving stock (Generic) deriving (AsUnion Responses) via (GenericAsUnion Responses Result)

instance GSOP.Generic Result @ and get an AsUnion instance for free.

There are a few predefined instances for constructors taking a single type corresponding to a simple response, and for empty responses, but in more general cases one either has to define an AsConstructor instance by hand, or derive it via GenericAsConstructor.

This type is meant to be used with deriving via in order to automatically generate an AsUnion instance using Generics.SOP.

See AsConstructor for more information and examples.

The result of parsing a response as a union alternative of type a.

StatusMismatch indicates that the response does not refer to the given alternative, because the status code does not match the one produced by that alternative.

UnrenderError and UnrenderSuccess represent respectively a failing and successful parse of the response body as a value of type a.

The UnrenderResult type constructor has monad and alternative instances corresponding to those of 'Either (Maybe (Last String)) a'.