Servant.API.ContentTypes

A collection of basic Content-Types (also known as Internet Media Types, or MIME types). Additionally, this module provides classes that encapsulate how to serialize or deserialize values to or from a particular Content-Type.

Content-Types are used in ReqBody and the method combinators:

>>> type MyEndpoint = ReqBody '[JSON, PlainText] Book :> Put '[JSON, PlainText] Book

Meaning the endpoint accepts requests of Content-Type application/json or text/plain;charset-utf8, and returns data in either one of those formats (depending on the Accept header).

If you would like to support Content-Types beyond those provided here, then:

1. Declare a new data type with no constructors (e.g. data HTML).
2. Make an instance of it for Accept.
3. If you want to be able to serialize data *into* that Content-Type, make an instance of it for MimeRender.
4. If you want to be able to deserialize data *from* that Content-Type, make an instance of it for MimeUnrender.

Note that roles are reversed in servant-server and servant-client: to be able to serve (or even typecheck) a Get '[JSON, XML] MyData, you'll need to have the appropriate MimeRender instances in scope, whereas to query that endpoint with servant-client, you'll need a MimeUnrender instance in scope.

Provided Content-Types

data JSON

Instances

Accept JSON

application/json

Defined in Servant.API.ContentTypes

Methods

contentType :: Proxy JSON -> MediaType

contentTypes :: Proxy JSON -> NonEmpty MediaType

ToJSON a => MimeRender JSON a

encode

Defined in Servant.API.ContentTypes

Methods

mimeRender :: Proxy JSON -> a -> ByteString

FromJSON a => MimeUnrender JSON a

eitherDecode

Defined in Servant.API.ContentTypes

Methods

mimeUnrender :: Proxy JSON -> ByteString -> Either String a

mimeUnrenderWithType :: Proxy JSON -> MediaType -> ByteString -> Either String a

MimeRender JSON a => MimeRender JSON (WithStatus _status a)

Defined in Servant.API.UVerb

Methods

mimeRender :: Proxy JSON -> WithStatus _status a -> ByteString

MimeUnrender JSON a => MimeUnrender JSON (WithStatus _status a)

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)

data PlainText

Instances

Accept PlainText

text/plain;charset=utf-8

Defined in Servant.API.ContentTypes

Methods

contentType :: Proxy PlainText -> MediaType

contentTypes :: Proxy PlainText -> NonEmpty MediaType

MimeRender PlainText Text

fromStrict . TextS.encodeUtf8

Defined in Servant.API.ContentTypes

Methods

mimeRender :: Proxy PlainText -> Text -> ByteString

MimeRender PlainText Text

encodeUtf8

Defined in Servant.API.ContentTypes

Methods

mimeRender :: Proxy PlainText -> Text -> ByteString

MimeRender PlainText String

BC.pack

Defined in Servant.API.ContentTypes

Methods

mimeRender :: Proxy PlainText -> String -> ByteString

MimeUnrender PlainText Text

left show . TextS.decodeUtf8' . toStrict

Defined in Servant.API.ContentTypes

Methods

mimeUnrender :: Proxy PlainText -> ByteString -> Either String Text

mimeUnrenderWithType :: Proxy PlainText -> MediaType -> ByteString -> Either String Text

MimeUnrender PlainText Text

left show . TextL.decodeUtf8'

Defined in Servant.API.ContentTypes

Methods

mimeUnrender :: Proxy PlainText -> ByteString -> Either String Text

mimeUnrenderWithType :: Proxy PlainText -> MediaType -> ByteString -> Either String Text

MimeUnrender PlainText String

Right . BC.unpack

Defined in Servant.API.ContentTypes

Methods

mimeUnrender :: Proxy PlainText -> ByteString -> Either String String

mimeUnrenderWithType :: Proxy PlainText -> MediaType -> ByteString -> Either String String

MimeRender PlainText a => MimeRender PlainText (WithStatus _status a)

Defined in Servant.API.UVerb

Methods

mimeRender :: Proxy PlainText -> WithStatus _status a -> ByteString

MimeUnrender PlainText a => MimeUnrender PlainText (WithStatus _status a)

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)

data FormUrlEncoded

Instances

Accept FormUrlEncoded

application/x-www-form-urlencoded

Defined in Servant.API.ContentTypes

Methods

contentType :: Proxy FormUrlEncoded -> MediaType

contentTypes :: Proxy FormUrlEncoded -> NonEmpty MediaType

ToForm a => MimeRender FormUrlEncoded a

urlEncodeAsForm Note that the mimeUnrender p (mimeRender p x) == Right x law only holds if every element of x is non-null (i.e., not ("", ""))

Defined in Servant.API.ContentTypes

Methods

mimeRender :: Proxy FormUrlEncoded -> a -> ByteString

FromForm a => MimeUnrender FormUrlEncoded a

urlDecodeAsForm Note that the mimeUnrender p (mimeRender p x) == Right x law only holds if every element of x is non-null (i.e., not ("", ""))

Defined in Servant.API.ContentTypes

Methods

mimeUnrender :: Proxy FormUrlEncoded -> ByteString -> Either String a

mimeUnrenderWithType :: Proxy FormUrlEncoded -> MediaType -> ByteString -> Either String a

MimeRender FormUrlEncoded a => MimeRender FormUrlEncoded (WithStatus _status a)

Defined in Servant.API.UVerb

Methods

mimeRender :: Proxy FormUrlEncoded -> WithStatus _status a -> ByteString

MimeUnrender FormUrlEncoded a => MimeUnrender FormUrlEncoded (WithStatus _status a)

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)

data OctetStream

Instances

Accept OctetStream

application/octet-stream

Defined in Servant.API.ContentTypes

Methods

contentType :: Proxy OctetStream -> MediaType

contentTypes :: Proxy OctetStream -> NonEmpty MediaType

MimeRender OctetStream ByteString

fromStrict

Defined in Servant.API.ContentTypes

Methods

mimeRender :: Proxy OctetStream -> ByteString -> ByteString0

MimeRender OctetStream ByteString

id

Defined in Servant.API.ContentTypes

Methods

mimeRender :: Proxy OctetStream -> ByteString -> ByteString

MimeUnrender OctetStream ByteString

Right . toStrict

Defined in Servant.API.ContentTypes

Methods

mimeUnrender :: Proxy OctetStream -> ByteString0 -> Either String ByteString

mimeUnrenderWithType :: Proxy OctetStream -> MediaType -> ByteString0 -> Either String ByteString

MimeUnrender OctetStream ByteString

Right . id

Defined in Servant.API.ContentTypes

Methods

mimeUnrender :: Proxy OctetStream -> ByteString -> Either String ByteString

mimeUnrenderWithType :: Proxy OctetStream -> MediaType -> ByteString -> Either String ByteString

MimeRender OctetStream a => MimeRender OctetStream (WithStatus _status a)

Defined in Servant.API.UVerb

Methods

mimeRender :: Proxy OctetStream -> WithStatus _status a -> ByteString

MimeUnrender OctetStream a => MimeUnrender OctetStream (WithStatus _status a)

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)

Building your own Content-Type

class Accept ctype where

Instances of Accept represent mimetypes. They are used for matching against the Accept HTTP header of the request, and for setting the Content-Type header of the response

Example:

>>> import Network.HTTP.Media ((//), (/:))
>>> data HTML
>>> :{
instance Accept HTML where
   contentType _ = "text" // "html" /: ("charset", "utf-8")
:}

Minimal complete definition

contentType | contentTypes

Methods

contentType :: Proxy ctype -> MediaType

contentTypes :: Proxy ctype -> NonEmpty MediaType

Instances

Accept FormUrlEncoded

application/x-www-form-urlencoded

Defined in Servant.API.ContentTypes

Methods

contentType :: Proxy FormUrlEncoded -> MediaType

contentTypes :: Proxy FormUrlEncoded -> NonEmpty MediaType

Accept JSON

application/json

Defined in Servant.API.ContentTypes

Methods

contentType :: Proxy JSON -> MediaType

contentTypes :: Proxy JSON -> NonEmpty MediaType

Accept OctetStream

application/octet-stream

Defined in Servant.API.ContentTypes

Methods

contentType :: Proxy OctetStream -> MediaType

contentTypes :: Proxy OctetStream -> NonEmpty MediaType

Accept PlainText

text/plain;charset=utf-8

Defined in Servant.API.ContentTypes

Methods

contentType :: Proxy PlainText -> MediaType

contentTypes :: Proxy PlainText -> NonEmpty MediaType

class Accept ctype => MimeRender ctype a where

Instantiate this class to register a way of serializing a type based on the Accept header.

Example:

data MyContentType

instance Accept MyContentType where
   contentType _ = "example" // "prs.me.mine" /: ("charset", "utf-8")

instance Show a => MimeRender MyContentType a where
   mimeRender _ val = pack ("This is MINE! " ++ show val)

type MyAPI = "path" :> Get '[MyContentType] Int

Methods

mimeRender :: Proxy ctype -> a -> ByteString

Instances

ToForm a => MimeRender FormUrlEncoded a

urlEncodeAsForm Note that the mimeUnrender p (mimeRender p x) == Right x law only holds if every element of x is non-null (i.e., not ("", ""))

Defined in Servant.API.ContentTypes

Methods

mimeRender :: Proxy FormUrlEncoded -> a -> ByteString

ToJSON a => MimeRender JSON a

encode

Defined in Servant.API.ContentTypes

Methods

mimeRender :: Proxy JSON -> a -> ByteString

MimeRender OctetStream ByteString

fromStrict

Defined in Servant.API.ContentTypes

Methods

mimeRender :: Proxy OctetStream -> ByteString -> ByteString0

MimeRender OctetStream ByteString

id

Defined in Servant.API.ContentTypes

Methods

mimeRender :: Proxy OctetStream -> ByteString -> ByteString

MimeRender PlainText Text

fromStrict . TextS.encodeUtf8

Defined in Servant.API.ContentTypes

Methods

mimeRender :: Proxy PlainText -> Text -> ByteString

MimeRender PlainText Text

encodeUtf8

Defined in Servant.API.ContentTypes

Methods

mimeRender :: Proxy PlainText -> Text -> ByteString

MimeRender PlainText String

BC.pack

Defined in Servant.API.ContentTypes

Methods

mimeRender :: Proxy PlainText -> String -> ByteString

MimeRender FormUrlEncoded a => MimeRender FormUrlEncoded (WithStatus _status a)

Defined in Servant.API.UVerb

Methods

mimeRender :: Proxy FormUrlEncoded -> WithStatus _status a -> ByteString

MimeRender JSON a => MimeRender JSON (WithStatus _status a)

Defined in Servant.API.UVerb

Methods

mimeRender :: Proxy JSON -> WithStatus _status a -> ByteString

MimeRender OctetStream a => MimeRender OctetStream (WithStatus _status a)

Defined in Servant.API.UVerb

Methods

mimeRender :: Proxy OctetStream -> WithStatus _status a -> ByteString

MimeRender PlainText a => MimeRender PlainText (WithStatus _status a)

Defined in Servant.API.UVerb

Methods

mimeRender :: Proxy PlainText -> WithStatus _status a -> ByteString

class Accept ctype => MimeUnrender ctype a where

Instantiate this class to register a way of deserializing a type based on the request's Content-Type header.

>>> import Network.HTTP.Media hiding (Accept)
>>> import qualified Data.ByteString.Lazy.Char8 as BSC
>>> data MyContentType = MyContentType String

>>> :{
instance Accept MyContentType where
   contentType _ = "example" // "prs.me.mine" /: ("charset", "utf-8")
:}

>>> :{
instance Read a => MimeUnrender MyContentType a where
   mimeUnrender _ bs = case BSC.take 12 bs of
     "MyContentType" -> return . read . BSC.unpack $ BSC.drop 12 bs
     _ -> Left "didn't start with the magic incantation"
:}

>>> type MyAPI = "path" :> ReqBody '[MyContentType] Int :> Get '[JSON] Int

Minimal complete definition

mimeUnrender | mimeUnrenderWithType

Methods

mimeUnrender :: Proxy ctype -> ByteString -> Either String a

mimeUnrenderWithType :: Proxy ctype -> MediaType -> ByteString -> Either String a

Variant which is given the actual MediaType provided by the other party.

In the most cases you don't want to branch based on the MediaType. See pr552 for a motivating example.

Instances

FromForm a => MimeUnrender FormUrlEncoded a

urlDecodeAsForm Note that the mimeUnrender p (mimeRender p x) == Right x law only holds if every element of x is non-null (i.e., not ("", ""))

Defined in Servant.API.ContentTypes

Methods

mimeUnrender :: Proxy FormUrlEncoded -> ByteString -> Either String a

mimeUnrenderWithType :: Proxy FormUrlEncoded -> MediaType -> ByteString -> Either String a

FromJSON a => MimeUnrender JSON a

eitherDecode

Defined in Servant.API.ContentTypes

Methods

mimeUnrender :: Proxy JSON -> ByteString -> Either String a

mimeUnrenderWithType :: Proxy JSON -> MediaType -> ByteString -> Either String a

MimeUnrender OctetStream ByteString

Right . toStrict

Defined in Servant.API.ContentTypes

Methods

mimeUnrender :: Proxy OctetStream -> ByteString0 -> Either String ByteString

mimeUnrenderWithType :: Proxy OctetStream -> MediaType -> ByteString0 -> Either String ByteString

MimeUnrender OctetStream ByteString

Right . id

Defined in Servant.API.ContentTypes

Methods

mimeUnrender :: Proxy OctetStream -> ByteString -> Either String ByteString

mimeUnrenderWithType :: Proxy OctetStream -> MediaType -> ByteString -> Either String ByteString

MimeUnrender PlainText Text

left show . TextS.decodeUtf8' . toStrict

Defined in Servant.API.ContentTypes

Methods

mimeUnrender :: Proxy PlainText -> ByteString -> Either String Text

mimeUnrenderWithType :: Proxy PlainText -> MediaType -> ByteString -> Either String Text

MimeUnrender PlainText Text

left show . TextL.decodeUtf8'

Defined in Servant.API.ContentTypes

Methods

mimeUnrender :: Proxy PlainText -> ByteString -> Either String Text

mimeUnrenderWithType :: Proxy PlainText -> MediaType -> ByteString -> Either String Text

MimeUnrender PlainText String

Right . BC.unpack

Defined in Servant.API.ContentTypes

Methods

mimeUnrender :: Proxy PlainText -> ByteString -> Either String String

mimeUnrenderWithType :: Proxy PlainText -> MediaType -> ByteString -> Either String String

MimeUnrender FormUrlEncoded a => MimeUnrender FormUrlEncoded (WithStatus _status a)

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)

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)

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)

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)

NoContent

data NoContent

A type for responses without content-body.

Constructors

NoContent

Instances

Generic NoContent

Defined in Servant.API.ContentTypes

Associated Types

type Rep NoContent :: Type -> Type

Methods

from :: NoContent -> Rep NoContent x

to :: Rep NoContent x -> NoContent

Read NoContent

Defined in Servant.API.ContentTypes

Methods

readsPrec :: Int -> ReadS NoContent

readList :: ReadS [NoContent]

readPrec :: ReadPrec NoContent

readListPrec :: ReadPrec [NoContent]

Show NoContent

Defined in Servant.API.ContentTypes

Methods

showsPrec :: Int -> NoContent -> ShowS

show :: NoContent -> String

showList :: [NoContent] -> ShowS

NFData NoContent

Defined in Servant.API.ContentTypes

Methods

rnf :: NoContent -> ()

Eq NoContent

Defined in Servant.API.ContentTypes

Methods

(==) :: NoContent -> NoContent -> Bool

(/=) :: NoContent -> NoContent -> Bool

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.

Defined in Servant.API.UVerb

Associated Types

type StatusOf NoContent :: Nat

AllMime (ctyp ': (ctyp' ': ctyps)) => AllMimeRender (ctyp ': (ctyp' ': ctyps)) NoContent

Defined in Servant.API.ContentTypes

Methods

allMimeRender :: Proxy (ctyp ': (ctyp' ': ctyps)) -> NoContent -> [(MediaType, ByteString)]

Accept ctyp => AllMimeRender '[ctyp] NoContent

Defined in Servant.API.ContentTypes

Methods

allMimeRender :: Proxy '[ctyp] -> NoContent -> [(MediaType, ByteString)]

type Rep NoContent

Defined in Servant.API.ContentTypes

type Rep NoContent = D1 ('MetaData "NoContent" "Servant.API.ContentTypes" "servant-0.20.2-Gi9sNeCszk4lB7Qo1IEZK" 'False) (C1 ('MetaCons "NoContent" 'PrefixI 'False) (U1 :: Type -> Type))

type StatusOf NoContent

Defined in Servant.API.UVerb

type StatusOf NoContent = 204

Internal

newtype AcceptHeader

Constructors

AcceptHeader ByteString

Instances

Generic AcceptHeader

Defined in Servant.API.ContentTypes

Associated Types

type Rep AcceptHeader :: Type -> Type

Methods

from :: AcceptHeader -> Rep AcceptHeader x

to :: Rep AcceptHeader x -> AcceptHeader

Read AcceptHeader

Defined in Servant.API.ContentTypes

Methods

readsPrec :: Int -> ReadS AcceptHeader

readList :: ReadS [AcceptHeader]

readPrec :: ReadPrec AcceptHeader

readListPrec :: ReadPrec [AcceptHeader]

Show AcceptHeader

Defined in Servant.API.ContentTypes

Methods

showsPrec :: Int -> AcceptHeader -> ShowS

show :: AcceptHeader -> String

showList :: [AcceptHeader] -> ShowS

Eq AcceptHeader

Defined in Servant.API.ContentTypes

Methods

(==) :: AcceptHeader -> AcceptHeader -> Bool

(/=) :: AcceptHeader -> AcceptHeader -> Bool

type Rep AcceptHeader

Defined in Servant.API.ContentTypes

type Rep AcceptHeader = D1 ('MetaData "AcceptHeader" "Servant.API.ContentTypes" "servant-0.20.2-Gi9sNeCszk4lB7Qo1IEZK" 'True) (C1 ('MetaCons "AcceptHeader" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 ByteString)))

class AllMime list => AllCTRender (list :: [Type]) a where

Methods

handleAcceptH :: Proxy list -> AcceptHeader -> a -> Maybe (ByteString, ByteString)

Instances

(TypeError ('Text "No instance for (), use NoContent instead.") :: Constraint) => AllCTRender ('[] :: [Type]) ()

Defined in Servant.API.ContentTypes

Methods

handleAcceptH :: Proxy '[] -> AcceptHeader -> () -> Maybe (ByteString, ByteString)

(Accept ct, AllMime cts, AllMimeRender (ct ': cts) a) => AllCTRender (ct ': cts) a

Defined in Servant.API.ContentTypes

Methods

handleAcceptH :: Proxy (ct ': cts) -> AcceptHeader -> a -> Maybe (ByteString, ByteString)

class AllCTUnrender (list :: [Type]) a where

Minimal complete definition

canHandleCTypeH

Methods

canHandleCTypeH :: Proxy list -> ByteString -> Maybe (ByteString -> Either String a)

handleCTypeH :: Proxy list -> ByteString -> ByteString -> Maybe (Either String a)

Instances

AllMimeUnrender ctyps a => AllCTUnrender ctyps a

Defined in Servant.API.ContentTypes

Methods

canHandleCTypeH :: Proxy ctyps -> ByteString -> Maybe (ByteString -> Either String a)

handleCTypeH :: Proxy ctyps -> ByteString -> ByteString -> Maybe (Either String a)

class AllMime (list :: [Type]) where

Methods

allMime :: Proxy list -> [MediaType]

Instances

AllMime ('[] :: [Type])

Defined in Servant.API.ContentTypes

Methods

allMime :: Proxy '[] -> [MediaType]

(Accept ctyp, AllMime ctyps) => AllMime (ctyp ': ctyps)

Defined in Servant.API.ContentTypes

Methods

allMime :: Proxy (ctyp ': ctyps) -> [MediaType]

class AllMime list => AllMimeRender (list :: [Type]) a where

Methods

allMimeRender :: Proxy list -> a -> [(MediaType, ByteString)]

Instances

AllMime (ctyp ': (ctyp' ': ctyps)) => AllMimeRender (ctyp ': (ctyp' ': ctyps)) NoContent

Defined in Servant.API.ContentTypes

Methods

allMimeRender :: Proxy (ctyp ': (ctyp' ': ctyps)) -> NoContent -> [(MediaType, ByteString)]

(MimeRender ctyp a, AllMimeRender (ctyp' ': ctyps) a) => AllMimeRender (ctyp ': (ctyp' ': ctyps)) a

Defined in Servant.API.ContentTypes

Methods

allMimeRender :: Proxy (ctyp ': (ctyp' ': ctyps)) -> a -> [(MediaType, ByteString)]

Accept ctyp => AllMimeRender '[ctyp] NoContent

Defined in Servant.API.ContentTypes

Methods

allMimeRender :: Proxy '[ctyp] -> NoContent -> [(MediaType, ByteString)]

MimeRender ctyp a => AllMimeRender '[ctyp] a

Defined in Servant.API.ContentTypes

Methods

allMimeRender :: Proxy '[ctyp] -> a -> [(MediaType, ByteString)]

class AllMime list => AllMimeUnrender (list :: [Type]) a where

Methods

allMimeUnrender :: Proxy list -> [(MediaType, ByteString -> Either String a)]

Instances

AllMimeUnrender ('[] :: [Type]) a

Defined in Servant.API.ContentTypes

Methods

allMimeUnrender :: Proxy '[] -> [(MediaType, ByteString -> Either String a)]

(MimeUnrender ctyp a, AllMimeUnrender ctyps a) => AllMimeUnrender (ctyp ': ctyps) a

Defined in Servant.API.ContentTypes

Methods

allMimeUnrender :: Proxy (ctyp ': ctyps) -> [(MediaType, ByteString -> Either String a)]

eitherDecodeLenient :: FromJSON a => ByteString -> Either String a

Deprecated: use eitherDecode instead

Deprecated: since aeson version 0.9 eitherDecode has lenient behavior.

canHandleAcceptH :: AllMime list => Proxy list -> AcceptHeader -> Bool