servant-0.20.1: A family of combinators for defining webservices APIs
Safe HaskellSafe-Inferred
LanguageHaskell2010

Servant.API.ContentTypes

Description

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.

Synopsis

Provided Content-Types

data JSON #

Instances

Instances details
Accept JSON #
application/json
Instance details

Defined in Servant.API.ContentTypes

ToJSON a => MimeRender JSON a #

encode

Instance details

Defined in Servant.API.ContentTypes

Methods

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

FromJSON a => MimeUnrender JSON a #

eitherDecode

Instance details

Defined in Servant.API.ContentTypes

MimeRender JSON a => MimeRender JSON (WithStatus _status a) # 
Instance details

Defined in Servant.API.UVerb

Methods

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

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) #

data PlainText #

Instances

Instances details
Accept PlainText #
text/plain;charset=utf-8
Instance details

Defined in Servant.API.ContentTypes

MimeRender PlainText Text #
fromStrict . TextS.encodeUtf8
Instance details

Defined in Servant.API.ContentTypes

Methods

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

MimeRender PlainText Text #

encodeUtf8

Instance details

Defined in Servant.API.ContentTypes

Methods

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

MimeRender PlainText String #
BC.pack
Instance details

Defined in Servant.API.ContentTypes

MimeUnrender PlainText Text #
left show . TextS.decodeUtf8' . toStrict
Instance details

Defined in Servant.API.ContentTypes

MimeUnrender PlainText Text #
left show . TextL.decodeUtf8'
Instance details

Defined in Servant.API.ContentTypes

MimeUnrender PlainText String #
Right . BC.unpack
Instance details

Defined in Servant.API.ContentTypes

MimeRender PlainText a => MimeRender PlainText (WithStatus _status a) # 
Instance details

Defined in Servant.API.UVerb

Methods

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

MimeUnrender PlainText a => MimeUnrender PlainText (WithStatus _status a) # 
Instance details

Defined in Servant.API.UVerb

data FormUrlEncoded #

Instances

Instances details
Accept FormUrlEncoded #
application/x-www-form-urlencoded
Instance details

Defined in Servant.API.ContentTypes

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

Instance details

Defined in Servant.API.ContentTypes

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

Instance details

Defined in Servant.API.ContentTypes

MimeRender FormUrlEncoded a => MimeRender FormUrlEncoded (WithStatus _status a) # 
Instance details

Defined in Servant.API.UVerb

MimeUnrender FormUrlEncoded a => MimeUnrender FormUrlEncoded (WithStatus _status a) # 
Instance details

Defined in Servant.API.UVerb

data OctetStream #

Instances

Instances details
Accept OctetStream #
application/octet-stream
Instance details

Defined in Servant.API.ContentTypes

MimeRender OctetStream ByteString #

fromStrict

Instance details

Defined in Servant.API.ContentTypes

MimeRender OctetStream ByteString #
id
Instance details

Defined in Servant.API.ContentTypes

MimeUnrender OctetStream ByteString #
Right . toStrict
Instance details

Defined in Servant.API.ContentTypes

MimeUnrender OctetStream ByteString #
Right . id
Instance details

Defined in Servant.API.ContentTypes

MimeRender OctetStream a => MimeRender OctetStream (WithStatus _status a) # 
Instance details

Defined in Servant.API.UVerb

MimeUnrender OctetStream a => MimeUnrender OctetStream (WithStatus _status a) # 
Instance details

Defined in Servant.API.UVerb

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

Instances

Instances details
Accept FormUrlEncoded #
application/x-www-form-urlencoded
Instance details

Defined in Servant.API.ContentTypes

Accept JSON #
application/json
Instance details

Defined in Servant.API.ContentTypes

Accept OctetStream #
application/octet-stream
Instance details

Defined in Servant.API.ContentTypes

Accept PlainText #
text/plain;charset=utf-8
Instance details

Defined in Servant.API.ContentTypes

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

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

Instance details

Defined in Servant.API.ContentTypes

ToJSON a => MimeRender JSON a #

encode

Instance details

Defined in Servant.API.ContentTypes

Methods

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

MimeRender OctetStream ByteString #

fromStrict

Instance details

Defined in Servant.API.ContentTypes

MimeRender OctetStream ByteString #
id
Instance details

Defined in Servant.API.ContentTypes

MimeRender PlainText Text #
fromStrict . TextS.encodeUtf8
Instance details

Defined in Servant.API.ContentTypes

Methods

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

MimeRender PlainText Text #

encodeUtf8

Instance details

Defined in Servant.API.ContentTypes

Methods

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

MimeRender PlainText String #
BC.pack
Instance details

Defined in Servant.API.ContentTypes

MimeRender FormUrlEncoded a => MimeRender FormUrlEncoded (WithStatus _status a) # 
Instance details

Defined in Servant.API.UVerb

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

MimeRender PlainText a => MimeRender PlainText (WithStatus _status a) # 
Instance details

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

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

Instance details

Defined in Servant.API.ContentTypes

FromJSON a => MimeUnrender JSON a #

eitherDecode

Instance details

Defined in Servant.API.ContentTypes

MimeUnrender OctetStream ByteString #
Right . toStrict
Instance details

Defined in Servant.API.ContentTypes

MimeUnrender OctetStream ByteString #
Right . id
Instance details

Defined in Servant.API.ContentTypes

MimeUnrender PlainText Text #
left show . TextS.decodeUtf8' . toStrict
Instance details

Defined in Servant.API.ContentTypes

MimeUnrender PlainText Text #
left show . TextL.decodeUtf8'
Instance details

Defined in Servant.API.ContentTypes

MimeUnrender PlainText String #
Right . BC.unpack
Instance details

Defined in Servant.API.ContentTypes

MimeUnrender FormUrlEncoded a => MimeUnrender FormUrlEncoded (WithStatus _status a) # 
Instance details

Defined in Servant.API.UVerb

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

MimeUnrender PlainText a => MimeUnrender PlainText (WithStatus _status a) # 
Instance details

Defined in Servant.API.UVerb

NoContent

data NoContent #

A type for responses without content-body.

Constructors

NoContent 

Instances

Instances details
Generic NoContent # 
Instance details

Defined in Servant.API.ContentTypes

Associated Types

type Rep NoContent :: Type -> Type #

Read NoContent # 
Instance details

Defined in Servant.API.ContentTypes

Methods

readsPrec :: Int -> ReadS NoContent #

readList :: ReadS [NoContent] #

readPrec :: ReadPrec NoContent #

readListPrec :: ReadPrec [NoContent] #

Show NoContent # 
Instance details

Defined in Servant.API.ContentTypes

Methods

showsPrec :: Int -> NoContent -> ShowS

show :: NoContent -> String

showList :: [NoContent] -> ShowS

NFData NoContent # 
Instance details

Defined in Servant.API.ContentTypes

Methods

rnf :: NoContent -> ()

Eq NoContent # 
Instance details

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.

Instance details

Defined in Servant.API.UVerb

Associated Types

type StatusOf NoContent :: Nat #

AllMime (ctyp ': (ctyp' ': ctyps)) => AllMimeRender (ctyp ': (ctyp' ': ctyps)) NoContent # 
Instance details

Defined in Servant.API.ContentTypes

Methods

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

Accept ctyp => AllMimeRender '[ctyp] NoContent # 
Instance details

Defined in Servant.API.ContentTypes

Methods

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

type Rep NoContent # 
Instance details

Defined in Servant.API.ContentTypes

type Rep NoContent = D1 ('MetaData "NoContent" "Servant.API.ContentTypes" "servant-0.20.1-2y7DLWEzubY4ToLPQej775" 'False) (C1 ('MetaCons "NoContent" 'PrefixI 'False) (U1 :: Type -> Type))
type StatusOf NoContent # 
Instance details

Defined in Servant.API.UVerb

type StatusOf NoContent = 204

Internal

newtype AcceptHeader #

Constructors

AcceptHeader ByteString 

Instances

Instances details
Generic AcceptHeader # 
Instance details

Defined in Servant.API.ContentTypes

Associated Types

type Rep AcceptHeader :: Type -> Type #

Read AcceptHeader # 
Instance details

Defined in Servant.API.ContentTypes

Show AcceptHeader # 
Instance details

Defined in Servant.API.ContentTypes

Methods

showsPrec :: Int -> AcceptHeader -> ShowS

show :: AcceptHeader -> String

showList :: [AcceptHeader] -> ShowS

Eq AcceptHeader # 
Instance details

Defined in Servant.API.ContentTypes

Methods

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

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

type Rep AcceptHeader # 
Instance details

Defined in Servant.API.ContentTypes

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

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

Methods

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

Instances

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

Defined in Servant.API.ContentTypes

Methods

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

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

Defined in Servant.API.ContentTypes

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

Instances details
AllMimeUnrender ctyps a => AllCTUnrender ctyps a # 
Instance details

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 :: [*]) where #

Methods

allMime :: Proxy list -> [MediaType] #

Instances

Instances details
AllMime ('[] :: [Type]) # 
Instance details

Defined in Servant.API.ContentTypes

Methods

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

(Accept ctyp, AllMime ctyps) => AllMime (ctyp ': ctyps) # 
Instance details

Defined in Servant.API.ContentTypes

Methods

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

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

Methods

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

Instances

Instances details
AllMime (ctyp ': (ctyp' ': ctyps)) => AllMimeRender (ctyp ': (ctyp' ': ctyps)) NoContent # 
Instance details

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 # 
Instance details

Defined in Servant.API.ContentTypes

Methods

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

Accept ctyp => AllMimeRender '[ctyp] NoContent # 
Instance details

Defined in Servant.API.ContentTypes

Methods

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

MimeRender ctyp a => AllMimeRender '[ctyp] a # 
Instance details

Defined in Servant.API.ContentTypes

Methods

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

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

Methods

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

Instances

Instances details
AllMimeUnrender ('[] :: [Type]) a # 
Instance details

Defined in Servant.API.ContentTypes

Methods

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

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

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 #