| Safe Haskell | None |
|---|---|
| Language | Haskell2010 |
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:
- Declare a new data type with no constructors (e.g.
data HTML). - Make an instance of it for
Accept. - If you want to be able to serialize data *into* that
Content-Type, make an instance of it for
MimeRender. - 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
- data JSON
- data PlainText
- data FormUrlEncoded
- data OctetStream
- class Accept ctype where
- contentType :: Proxy ctype -> MediaType
- contentTypes :: Proxy ctype -> NonEmpty MediaType
- class Accept ctype => MimeRender ctype a where
- mimeRender :: Proxy ctype -> a -> ByteString
- class Accept ctype => MimeUnrender ctype a where
- mimeUnrender :: Proxy ctype -> ByteString -> Either String a
- mimeUnrenderWithType :: Proxy ctype -> MediaType -> ByteString -> Either String a
- data NoContent = NoContent
- newtype AcceptHeader = AcceptHeader ByteString
- class AllMime list => AllCTRender (list :: [*]) a where
- handleAcceptH :: Proxy list -> AcceptHeader -> a -> Maybe (ByteString, ByteString)
- class AllCTUnrender (list :: [*]) a where
- canHandleCTypeH :: Proxy list -> ByteString -> Maybe (ByteString -> Either String a)
- handleCTypeH :: Proxy list -> ByteString -> ByteString -> Maybe (Either String a)
- class AllMime (list :: [*]) where
- class AllMime list => AllMimeRender (list :: [*]) a where
- allMimeRender :: Proxy list -> a -> [(MediaType, ByteString)]
- class AllMime list => AllMimeUnrender (list :: [*]) a where
- allMimeUnrender :: Proxy list -> [(MediaType, ByteString -> Either String a)]
- eitherDecodeLenient :: FromJSON a => ByteString -> Either String a
- canHandleAcceptH :: AllMime list => Proxy list -> AcceptHeader -> Bool
Provided Content-Types
Instances
| Accept JSON Source # | application/json |
Defined in Servant.API.ContentTypes | |
| FromJSON a => MimeUnrender JSON a Source # |
|
Defined in Servant.API.ContentTypes Methods mimeUnrender :: Proxy JSON -> ByteString -> Either String a Source # mimeUnrenderWithType :: Proxy JSON -> MediaType -> ByteString -> Either String a Source # | |
| ToJSON a => MimeRender JSON a Source # | |
Defined in Servant.API.ContentTypes Methods mimeRender :: Proxy JSON -> a -> ByteString Source # | |
| MimeUnrender JSON a => MimeUnrender JSON (WithStatus _status a) Source # | |
Defined in Servant.API.UVerb Methods mimeUnrender :: Proxy JSON -> ByteString -> Either String (WithStatus _status a) Source # mimeUnrenderWithType :: Proxy JSON -> MediaType -> ByteString -> Either String (WithStatus _status a) Source # | |
| MimeRender JSON a => MimeRender JSON (WithStatus _status a) Source # | |
Defined in Servant.API.UVerb Methods mimeRender :: Proxy JSON -> WithStatus _status a -> ByteString Source # | |
Instances
data FormUrlEncoded Source #
Instances
data OctetStream Source #
Instances
Building your own Content-Type
class Accept ctype where Source #
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
Methods
contentType :: Proxy ctype -> MediaType Source #
Instances
| Accept OctetStream Source # | application/octet-stream |
Defined in Servant.API.ContentTypes Methods contentType :: Proxy OctetStream -> MediaType Source # contentTypes :: Proxy OctetStream -> NonEmpty MediaType Source # | |
| Accept FormUrlEncoded Source # | application/x-www-form-urlencoded |
Defined in Servant.API.ContentTypes Methods contentType :: Proxy FormUrlEncoded -> MediaType Source # contentTypes :: Proxy FormUrlEncoded -> NonEmpty MediaType Source # | |
| Accept PlainText Source # | text/plain;charset=utf-8 |
Defined in Servant.API.ContentTypes | |
| Accept JSON Source # | application/json |
Defined in Servant.API.ContentTypes | |
class Accept ctype => MimeRender ctype a where Source #
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] IntMethods
mimeRender :: Proxy ctype -> a -> ByteString Source #
Instances
class Accept ctype => MimeUnrender ctype a where Source #
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
Methods
mimeUnrender :: Proxy ctype -> ByteString -> Either String a Source #
mimeUnrenderWithType :: Proxy ctype -> MediaType -> ByteString -> Either String a Source #
Instances
NoContent
A type for responses without content-body.
Constructors
| NoContent |
Instances
| Eq NoContent Source # | |
| Read NoContent Source # | |
| Show NoContent Source # | |
| Generic NoContent Source # | |
| NFData NoContent Source # | |
Defined in Servant.API.ContentTypes | |
| HasStatus NoContent Source # | If an API can respond with |
| AllMime (ctyp ': (ctyp' ': ctyps)) => AllMimeRender (ctyp ': (ctyp' ': ctyps)) NoContent Source # | |
Defined in Servant.API.ContentTypes Methods allMimeRender :: Proxy (ctyp ': (ctyp' ': ctyps)) -> NoContent -> [(MediaType, ByteString)] Source # | |
| Accept ctyp => AllMimeRender '[ctyp] NoContent Source # | |
Defined in Servant.API.ContentTypes Methods allMimeRender :: Proxy '[ctyp] -> NoContent -> [(MediaType, ByteString)] Source # | |
| type Rep NoContent Source # | |
| type StatusOf NoContent Source # | |
Defined in Servant.API.UVerb | |
Internal
newtype AcceptHeader Source #
Constructors
| AcceptHeader ByteString |
Instances
| Eq AcceptHeader Source # | |
Defined in Servant.API.ContentTypes | |
| Read AcceptHeader Source # | |
Defined in Servant.API.ContentTypes Methods readsPrec :: Int -> ReadS AcceptHeader # readList :: ReadS [AcceptHeader] # | |
| Show AcceptHeader Source # | |
Defined in Servant.API.ContentTypes Methods showsPrec :: Int -> AcceptHeader -> ShowS # show :: AcceptHeader -> String # showList :: [AcceptHeader] -> ShowS # | |
| Generic AcceptHeader Source # | |
Defined in Servant.API.ContentTypes Associated Types type Rep AcceptHeader :: Type -> Type # | |
| type Rep AcceptHeader Source # | |
Defined in Servant.API.ContentTypes type Rep AcceptHeader = D1 ('MetaData "AcceptHeader" "Servant.API.ContentTypes" "servant-0.19-KR5MGMkCgzD3mkDu6Wi5Ug" 'True) (C1 ('MetaCons "AcceptHeader" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 ByteString))) | |
class AllMime list => AllCTRender (list :: [*]) a where Source #
Methods
handleAcceptH :: Proxy list -> AcceptHeader -> a -> Maybe (ByteString, ByteString) Source #
Instances
| (TypeError ('Text "No instance for (), use NoContent instead.") :: Constraint) => AllCTRender ('[] :: [Type]) () Source # | |
Defined in Servant.API.ContentTypes Methods handleAcceptH :: Proxy '[] -> AcceptHeader -> () -> Maybe (ByteString, ByteString) Source # | |
| (Accept ct, AllMime cts, AllMimeRender (ct ': cts) a) => AllCTRender (ct ': cts) a Source # | |
Defined in Servant.API.ContentTypes Methods handleAcceptH :: Proxy (ct ': cts) -> AcceptHeader -> a -> Maybe (ByteString, ByteString) Source # | |
class AllCTUnrender (list :: [*]) a where Source #
Minimal complete definition
Methods
canHandleCTypeH :: Proxy list -> ByteString -> Maybe (ByteString -> Either String a) Source #
handleCTypeH :: Proxy list -> ByteString -> ByteString -> Maybe (Either String a) Source #
Instances
| AllMimeUnrender ctyps a => AllCTUnrender ctyps a Source # | |
Defined in Servant.API.ContentTypes Methods canHandleCTypeH :: Proxy ctyps -> ByteString -> Maybe (ByteString -> Either String a) Source # handleCTypeH :: Proxy ctyps -> ByteString -> ByteString -> Maybe (Either String a) Source # | |
class AllMime list => AllMimeRender (list :: [*]) a where Source #
Methods
allMimeRender :: Proxy list -> a -> [(MediaType, ByteString)] Source #
Instances
| AllMime (ctyp ': (ctyp' ': ctyps)) => AllMimeRender (ctyp ': (ctyp' ': ctyps)) NoContent Source # | |
Defined in Servant.API.ContentTypes Methods allMimeRender :: Proxy (ctyp ': (ctyp' ': ctyps)) -> NoContent -> [(MediaType, ByteString)] Source # | |
| Accept ctyp => AllMimeRender '[ctyp] NoContent Source # | |
Defined in Servant.API.ContentTypes Methods allMimeRender :: Proxy '[ctyp] -> NoContent -> [(MediaType, ByteString)] Source # | |
| (MimeRender ctyp a, AllMimeRender (ctyp' ': ctyps) a) => AllMimeRender (ctyp ': (ctyp' ': ctyps)) a Source # | |
Defined in Servant.API.ContentTypes Methods allMimeRender :: Proxy (ctyp ': (ctyp' ': ctyps)) -> a -> [(MediaType, ByteString)] Source # | |
| MimeRender ctyp a => AllMimeRender '[ctyp] a Source # | |
Defined in Servant.API.ContentTypes Methods allMimeRender :: Proxy '[ctyp] -> a -> [(MediaType, ByteString)] Source # | |
class AllMime list => AllMimeUnrender (list :: [*]) a where Source #
Methods
allMimeUnrender :: Proxy list -> [(MediaType, ByteString -> Either String a)] Source #
Instances
| AllMimeUnrender ('[] :: [Type]) a Source # | |
Defined in Servant.API.ContentTypes Methods allMimeUnrender :: Proxy '[] -> [(MediaType, ByteString -> Either String a)] Source # | |
| (MimeUnrender ctyp a, AllMimeUnrender ctyps a) => AllMimeUnrender (ctyp ': ctyps) a Source # | |
Defined in Servant.API.ContentTypes Methods allMimeUnrender :: Proxy (ctyp ': ctyps) -> [(MediaType, ByteString -> Either String a)] Source # | |
eitherDecodeLenient :: FromJSON a => ByteString -> Either String a Source #
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 IntRight 1
>>>eitherDecodeLenient "1 junk" :: Either String IntLeft "trailing junk after valid JSON: endOfInput"
canHandleAcceptH :: AllMime list => Proxy list -> AcceptHeader -> Bool Source #