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 :> Get '[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

Methods

contentType :: Proxy JSON ctype -> MediaType

contentTypes :: Proxy JSON ctype -> NonEmpty MediaType

FromJSON a => MimeUnrender * JSON a

eitherDecode

Methods

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

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

ToJSON a => MimeRender * JSON a

encode

Methods

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

data PlainText

Instances

Accept * PlainText

text/plain;charset=utf-8

Methods

contentType :: Proxy PlainText ctype -> MediaType

contentTypes :: Proxy PlainText ctype -> NonEmpty MediaType

MimeUnrender * PlainText String

Right . BC.unpack

Methods

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

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

MimeUnrender * PlainText Text

left show . TextS.decodeUtf8' . toStrict

Methods

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

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

MimeUnrender * PlainText Text

left show . TextL.decodeUtf8'

Methods

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

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

MimeRender * PlainText String

BC.pack

Methods

mimeRender :: Proxy PlainText String -> a -> ByteString

MimeRender * PlainText Text

fromStrict . TextS.encodeUtf8

Methods

mimeRender :: Proxy PlainText Text -> a -> ByteString

MimeRender * PlainText Text

encodeUtf8

Methods

mimeRender :: Proxy PlainText Text -> a -> ByteString

data FormUrlEncoded

Instances

Accept * FormUrlEncoded

application/x-www-form-urlencoded

Methods

contentType :: Proxy FormUrlEncoded ctype -> MediaType

contentTypes :: Proxy FormUrlEncoded ctype -> NonEmpty MediaType

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 ("", ""))

Methods

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

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

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 ("", ""))

Methods

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

data OctetStream

Instances

Accept * OctetStream

application/octet-stream

Methods

contentType :: Proxy OctetStream ctype -> MediaType

contentTypes :: Proxy OctetStream ctype -> NonEmpty MediaType

MimeUnrender * OctetStream ByteString

Right . toStrict

Methods

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

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

MimeUnrender * OctetStream ByteString

Right . id

Methods

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

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

MimeRender * OctetStream ByteString

fromStrict

Methods

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

MimeRender * OctetStream ByteString

id

Methods

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

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 * OctetStream

application/octet-stream

Methods

contentType :: Proxy OctetStream ctype -> MediaType

contentTypes :: Proxy OctetStream ctype -> NonEmpty MediaType

Accept * FormUrlEncoded

application/x-www-form-urlencoded

Methods

contentType :: Proxy FormUrlEncoded ctype -> MediaType

contentTypes :: Proxy FormUrlEncoded ctype -> NonEmpty MediaType

Accept * PlainText

text/plain;charset=utf-8

Methods

contentType :: Proxy PlainText ctype -> MediaType

contentTypes :: Proxy PlainText ctype -> NonEmpty MediaType

Accept * JSON

application/json

Methods

contentType :: Proxy JSON ctype -> MediaType

contentTypes :: Proxy JSON ctype -> 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

Minimal complete definition

mimeRender

Methods

mimeRender :: Proxy ctype -> a -> ByteString

Instances

MimeRender * OctetStream ByteString

fromStrict

Methods

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

MimeRender * OctetStream ByteString

id

Methods

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

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 ("", ""))

Methods

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

MimeRender * PlainText String

BC.pack

Methods

mimeRender :: Proxy PlainText String -> a -> ByteString

MimeRender * PlainText Text

fromStrict . TextS.encodeUtf8

Methods

mimeRender :: Proxy PlainText Text -> a -> ByteString

MimeRender * PlainText Text

encodeUtf8

Methods

mimeRender :: Proxy PlainText Text -> a -> ByteString

ToJSON a => MimeRender * JSON a

encode

Methods

mimeRender :: Proxy JSON a -> 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

MimeUnrender * OctetStream ByteString

Right . toStrict

Methods

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

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

MimeUnrender * OctetStream ByteString

Right . id

Methods

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

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

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 ("", ""))

Methods

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

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

MimeUnrender * PlainText String

Right . BC.unpack

Methods

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

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

MimeUnrender * PlainText Text

left show . TextS.decodeUtf8' . toStrict

Methods

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

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

MimeUnrender * PlainText Text

left show . TextL.decodeUtf8'

Methods

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

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

FromJSON a => MimeUnrender * JSON a

eitherDecode

Methods

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

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

NoContent

data NoContent

A type for responses without content-body.

Constructors

NoContent

Instances

Eq NoContent

Methods

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

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

Read NoContent

Methods

readsPrec :: Int -> ReadS NoContent

readList :: ReadS [NoContent]

readPrec :: ReadPrec NoContent

readListPrec :: ReadPrec [NoContent]

Show NoContent

Methods

showsPrec :: Int -> NoContent -> ShowS

show :: NoContent -> String

showList :: [NoContent] -> ShowS

Generic NoContent

Associated Types

type Rep NoContent :: * -> *

Methods

from :: NoContent -> Rep NoContent x

to :: Rep NoContent x -> NoContent

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

Methods

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

Accept * ctyp => AllMimeRender ((:) * ctyp ([] *)) NoContent

Methods

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

type Rep NoContent

type Rep NoContent = D1 * (MetaData "NoContent" "Servant.API.ContentTypes" "servant-0.13-C7ShdXgoa8S3GCHcjpSre" False) (C1 * (MetaCons "NoContent" PrefixI False) (U1 *))

Internal

newtype AcceptHeader

Constructors

AcceptHeader ByteString

Instances

Eq AcceptHeader

Methods

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

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

Read AcceptHeader

Methods

readsPrec :: Int -> ReadS AcceptHeader

readList :: ReadS [AcceptHeader]

readPrec :: ReadPrec AcceptHeader

readListPrec :: ReadPrec [AcceptHeader]

Show AcceptHeader

Methods

showsPrec :: Int -> AcceptHeader -> ShowS

show :: AcceptHeader -> String

showList :: [AcceptHeader] -> ShowS

Generic AcceptHeader

Associated Types

type Rep AcceptHeader :: * -> *

Methods

from :: AcceptHeader -> Rep AcceptHeader x

to :: Rep AcceptHeader x -> AcceptHeader

type Rep AcceptHeader

type Rep AcceptHeader = D1 * (MetaData "AcceptHeader" "Servant.API.ContentTypes" "servant-0.13-C7ShdXgoa8S3GCHcjpSre" True) (C1 * (MetaCons "AcceptHeader" PrefixI False) (S1 * (MetaSel (Nothing Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 * ByteString)))

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

Minimal complete definition

handleAcceptH

Methods

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

Instances

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

Methods

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

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

Methods

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

class AllCTUnrender (list :: [*]) 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

Methods

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

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

class AllMime (list :: [*]) where

Minimal complete definition

allMime

Methods

allMime :: Proxy list -> [MediaType]

Instances

AllMime ([] *)

Methods

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

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

Methods

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

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

Minimal complete definition

allMimeRender

Methods

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

Instances

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

Methods

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

Accept * ctyp => AllMimeRender ((:) * ctyp ([] *)) NoContent

Methods

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

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

Methods

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

MimeRender * ctyp a => AllMimeRender ((:) * ctyp ([] *)) a

Methods

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

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

Minimal complete definition

allMimeUnrender

Methods

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

Instances

AllMimeUnrender ([] *) a

Methods

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

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

Methods

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

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

Like eitherDecode but allows all JSON values instead of just objects and arrays.

Will handle trailing whitespace, but not trailing junk. ie.

>>> eitherDecodeLenient "1 " :: Either String Int
Right 1

>>> eitherDecodeLenient "1 junk" :: Either String Int
Left "trailing junk after valid JSON: endOfInput"

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