| Safe Haskell | None |
|---|---|
| Language | Haskell2010 |
Servant.API
Contents
- Combinators
- Accessing information from the request
- Actual endpoints, distinguished by HTTP method
- Sub-APIs defined as records of routes
- Streaming endpoints, distinguished by HTTP method
- Authentication
- Endpoints description
- Content Types
- Response Headers
- Untyped endpoints
- FromHttpApiData and ToHttpApiData
- Experimental modules
- Links
- Re-exports
Synopsis
- data (path :: k) :> (a :: *)
- data a :<|> b = a :<|> b
- data EmptyAPI = EmptyAPI
- data Strict
- data Lenient
- data Optional
- data Required
- data CaptureAll (sym :: Symbol ) (a :: *)
- data Capture' (mods :: [*]) (sym :: Symbol ) (a :: *)
- type Capture = Capture' '[]
- data Header' (mods :: [*]) (sym :: Symbol ) (a :: *)
- type Header = Header' '[ Optional , Strict ]
- data HttpVersion = HttpVersion { }
- data QueryFlag (sym :: Symbol )
- data QueryParams (sym :: Symbol ) (a :: *)
- data QueryParam' (mods :: [*]) (sym :: Symbol ) (a :: *)
- type QueryParam = QueryParam' '[ Optional , Strict ]
- data Fragment (a :: *)
- data ReqBody' (mods :: [*]) (contentTypes :: [*]) (a :: *)
- type ReqBody = ReqBody' '[ Required , Strict ]
- data RemoteHost
- data IsSecure
- type Vault = Vault RealWorld
- data WithNamedContext (name :: Symbol ) (subContext :: [*]) subApi
- data StdMethod
-
class
ReflectMethod
a
where
- reflectMethod :: Proxy a -> Method
- type GetPartialContent = Verb ' GET 206
- type PostResetContent = Verb ' POST 205
- type GetResetContent = Verb ' GET 205
- type PutNoContent = NoContentVerb ' PUT
- type PatchNoContent = NoContentVerb ' PATCH
- type DeleteNoContent = NoContentVerb ' DELETE
- type PostNoContent = NoContentVerb ' POST
- type GetNoContent = NoContentVerb ' GET
- type PutNonAuthoritative = Verb ' PUT 203
- type PatchNonAuthoritative = Verb ' PATCH 203
- type DeleteNonAuthoritative = Verb ' DELETE 203
- type PostNonAuthoritative = Verb ' POST 203
- type GetNonAuthoritative = Verb ' GET 203
- type PutAccepted = Verb ' PUT 202
- type PatchAccepted = Verb ' PATCH 202
- type DeleteAccepted = Verb ' DELETE 202
- type PostAccepted = Verb ' POST 202
- type GetAccepted = Verb ' GET 202
- type PutCreated = Verb ' PUT 201
- type PostCreated = Verb ' POST 201
- type Patch = Verb ' PATCH 200
- type Delete = Verb ' DELETE 200
- type Put = Verb ' PUT 200
- type Post = Verb ' POST 200
- type Get = Verb ' GET 200
- data NoContentVerb (method :: k1)
- data Verb (method :: k1) (statusCode :: Nat ) (contentTypes :: [*]) (a :: *)
- type family Unique xs :: Constraint where ...
- inject :: UElem x xs => f x -> NS f xs
- type IsMember (a :: u) (as :: [u]) = ( Unique as, CheckElemIsMember a as, UElem a as)
- type Union = NS I
- data UVerb (method :: StdMethod ) (contentTypes :: [*]) (as :: [*])
- newtype WithStatus (k :: Nat ) a = WithStatus a
- type family Statuses (as :: [*]) :: [ Nat ]
- type family Statuses (as :: [*]) :: [ Nat ]
- class KnownStatus ( StatusOf a) => HasStatus (a :: *) where
- statusOf :: forall a proxy. HasStatus a => proxy a -> Status
- data NamedRoutes (api :: * -> *)
- class GServantProduct f
- data AsApi
- type ToServantApi routes = ToServant routes AsApi
- type ToServant routes mode = GToServant ( Rep (routes mode))
-
class
GenericMode
mode
where
- type mode :- api :: *
- type GenericServant routes mode = ( GenericMode mode, Generic (routes mode), GServantProduct ( Rep (routes mode)))
- toServant :: GenericServant routes mode => routes mode -> ToServant routes mode
- fromServant :: GenericServant routes mode => ToServant routes mode -> routes mode
- genericApi :: GenericServant routes AsApi => Proxy routes -> Proxy ( ToServantApi routes)
- data NetstringFraming
- data NewlineFraming
- data NoFraming
-
class
FramingUnrender
strategy
where
- framingUnrender :: Monad m => Proxy strategy -> ( ByteString -> Either String a) -> SourceT m ByteString -> SourceT m a
-
class
FramingRender
strategy
where
- framingRender :: Monad m => Proxy strategy -> (a -> ByteString ) -> SourceT m a -> SourceT m ByteString
-
class
FromSourceIO
chunk a | a -> chunk
where
- fromSourceIO :: SourceIO chunk -> a
-
class
ToSourceIO
chunk a | a -> chunk
where
- toSourceIO :: a -> SourceIO chunk
- type SourceIO = SourceT IO
- data StreamBody' (mods :: [*]) (framing :: *) (contentType :: *) (a :: *)
- type StreamBody = StreamBody' '[]
- type StreamPost = Stream ' POST 200
- type StreamGet = Stream ' GET 200
- data Stream (method :: k1) (status :: Nat ) (framing :: *) (contentType :: *) (a :: *)
- data BasicAuthData = BasicAuthData { }
- data BasicAuth (realm :: Symbol ) (userData :: *)
- data Description (sym :: Symbol )
- data Summary (sym :: Symbol )
- data NoContent = NoContent
-
class
Accept
ctype =>
MimeUnrender
ctype a
where
- mimeUnrender :: Proxy ctype -> ByteString -> Either String a
- mimeUnrenderWithType :: Proxy ctype -> MediaType -> ByteString -> Either String a
-
class
Accept
ctype =>
MimeRender
ctype a
where
- mimeRender :: Proxy ctype -> a -> ByteString
-
class
Accept
ctype
where
- contentType :: Proxy ctype -> MediaType
- contentTypes :: Proxy ctype -> NonEmpty MediaType
- data OctetStream
- data FormUrlEncoded
- data PlainText
- data JSON
- class HasResponseHeader h a headers
- class AddHeader h v orig new | h v orig -> new, new -> h, new -> v, new -> orig
-
class
GetHeaders
ls
where
- getHeaders :: ls -> [ Header ]
-
class
BuildHeadersTo
hs
where
- buildHeadersTo :: [ Header ] -> HList hs
- data HList a where
- data ResponseHeader (sym :: Symbol ) a
-
data
Headers
ls a =
Headers
{
- getResponse :: a
- getHeadersHList :: HList ls
- addHeader :: AddHeader h v orig new => v -> orig -> new
- noHeader :: AddHeader h v orig new => orig -> new
- lookupResponseHeader :: HasResponseHeader h a headers => Headers headers r -> ResponseHeader h a
- data Raw
-
class
ToHttpApiData
a
where
- toUrlPiece :: a -> Text
- toEncodedUrlPiece :: a -> Builder
- toHeader :: a -> ByteString
- toQueryParam :: a -> Text
-
class
FromHttpApiData
a
where
- parseUrlPiece :: Text -> Either Text a
- parseHeader :: ByteString -> Either Text a
- parseQueryParam :: Text -> Either Text a
- data AuthProtect (tag :: k)
- data URI = URI { }
- type family IsElem endpoint api :: Constraint where ...
- type family IsElem' a s :: Constraint
- class HasLink endpoint where
- data Link
- safeLink :: forall endpoint api. ( IsElem endpoint api, HasLink endpoint) => Proxy api -> Proxy endpoint -> MkLink endpoint Link
- type family If (cond :: Bool ) (tru :: k) (fls :: k) :: k where ...
- data SBool (b :: Bool ) where
- class SBoolI (b :: Bool ) where
Combinators
data (path :: k) :> (a :: *) infixr 4 Source #
The contained API (second argument) can be found under
("/" ++ path)
(path being the first argument).
Example:
>>>-- GET /hello/world>>>-- returning a JSON encoded World value>>>type MyApi = "hello" :> "world" :> Get '[JSON] World
Instances
Type-level combinator for expressing subrouting:
:>
data a :<|> b infixr 3 Source #
Union of two APIs, first takes precedence in case of overlap.
Example:
>>>:{type MyApi = "books" :> Get '[JSON] [Book] -- GET /books :<|> "books" :> ReqBody '[JSON] Book :> Post '[JSON] () -- POST /books :}
Constructors
| a :<|> b infixr 3 |
Instances
| Bifunctor (:<|>) Source # | |
| Bitraversable (:<|>) Source # | |
|
Defined in Servant.API.Alternative Methods bitraverse :: Applicative f => (a -> f c) -> (b -> f d) -> (a :<|> b) -> f (c :<|> d) Source # |
|
| Bifoldable (:<|>) Source # | |
|
Defined in Servant.API.Alternative |
|
| Biapplicative (:<|>) Source # | |
| Functor ( (:<|>) a) Source # | |
| Foldable ( (:<|>) a) Source # | |
|
Defined in Servant.API.Alternative Methods fold :: Monoid m => (a :<|> m) -> m Source # foldMap :: Monoid m => (a0 -> m) -> (a :<|> a0) -> m Source # foldMap' :: Monoid m => (a0 -> m) -> (a :<|> a0) -> m Source # foldr :: (a0 -> b -> b) -> b -> (a :<|> a0) -> b Source # foldr' :: (a0 -> b -> b) -> b -> (a :<|> a0) -> b Source # foldl :: (b -> a0 -> b) -> b -> (a :<|> a0) -> b Source # foldl' :: (b -> a0 -> b) -> b -> (a :<|> a0) -> b Source # foldr1 :: (a0 -> a0 -> a0) -> (a :<|> a0) -> a0 Source # foldl1 :: (a0 -> a0 -> a0) -> (a :<|> a0) -> a0 Source # toList :: (a :<|> a0) -> [a0] Source # null :: (a :<|> a0) -> Bool Source # length :: (a :<|> a0) -> Int Source # elem :: Eq a0 => a0 -> (a :<|> a0) -> Bool Source # maximum :: Ord a0 => (a :<|> a0) -> a0 Source # minimum :: Ord a0 => (a :<|> a0) -> a0 Source # |
|
| Traversable ( (:<|>) a) Source # | |
|
Defined in Servant.API.Alternative |
|
| ( HasLink a, HasLink b) => HasLink (a :<|> b :: Type ) Source # | |
| ( Bounded a, Bounded b) => Bounded (a :<|> b) Source # | |
| ( Eq a, Eq b) => Eq (a :<|> b) Source # | |
| ( Show a, Show b) => Show (a :<|> b) Source # | |
| ( Semigroup a, Semigroup b) => Semigroup (a :<|> b) Source # | |
| ( Monoid a, Monoid b) => Monoid (a :<|> b) Source # | |
| type MkLink (a :<|> b :: Type ) r Source # | |
Type-level combinator for alternative endpoints:
:<|>
An empty API: one which serves nothing. Morally speaking, this should be
the unit of
:<|>
. Implementors of interpretations of API types should
treat
EmptyAPI
as close to the unit as possible.
Constructors
| EmptyAPI |
Instances
| Bounded EmptyAPI Source # | |
| Enum EmptyAPI Source # | |
|
Defined in Servant.API.Empty Methods succ :: EmptyAPI -> EmptyAPI Source # pred :: EmptyAPI -> EmptyAPI Source # toEnum :: Int -> EmptyAPI Source # fromEnum :: EmptyAPI -> Int Source # enumFrom :: EmptyAPI -> [ EmptyAPI ] Source # enumFromThen :: EmptyAPI -> EmptyAPI -> [ EmptyAPI ] Source # enumFromTo :: EmptyAPI -> EmptyAPI -> [ EmptyAPI ] Source # enumFromThenTo :: EmptyAPI -> EmptyAPI -> EmptyAPI -> [ EmptyAPI ] Source # |
|
| Eq EmptyAPI Source # | |
| Show EmptyAPI Source # | |
| HasLink EmptyAPI Source # | |
| type MkLink EmptyAPI a Source # | |
|
Defined in Servant.Links |
|
Type-level combinator for an empty API:
EmptyAPI
Strictly parsed argument. Not wrapped.
Instances
| ( KnownSymbol h, ToHttpApiData v) => AddHeader h v ( Headers (fst ': rest) a) ( Headers ( Header h v ': (fst ': rest)) a) Source # | |
|
Defined in Servant.API.ResponseHeaders Methods addOptionalHeader :: ResponseHeader h v -> Headers (fst ': rest) a -> Headers ( Header h v ': (fst ': rest)) a |
|
| HasResponseHeader h a ( Header h a ': rest) Source # | |
|
Defined in Servant.API.ResponseHeaders Methods hlistLookupHeader :: HList ( Header h a ': rest) -> ResponseHeader h a |
|
| ( KnownSymbol h, GetHeadersFromHList rest, ToHttpApiData v) => GetHeaders' ( Header h v ': rest) Source # | |
|
Defined in Servant.API.ResponseHeaders Methods getHeaders' :: Headers ( Header h v ': rest) a -> [ Header0 ] |
|
| ( FromHttpApiData v, BuildHeadersTo xs, KnownSymbol h) => BuildHeadersTo ( Header h v ': xs) Source # | |
|
Defined in Servant.API.ResponseHeaders |
|
Optional argument. Wrapped in
Maybe
.
Instances
| ( KnownSymbol h, ToHttpApiData v) => AddHeader h v ( Headers (fst ': rest) a) ( Headers ( Header h v ': (fst ': rest)) a) Source # | |
|
Defined in Servant.API.ResponseHeaders Methods addOptionalHeader :: ResponseHeader h v -> Headers (fst ': rest) a -> Headers ( Header h v ': (fst ': rest)) a |
|
| HasResponseHeader h a ( Header h a ': rest) Source # | |
|
Defined in Servant.API.ResponseHeaders Methods hlistLookupHeader :: HList ( Header h a ': rest) -> ResponseHeader h a |
|
| ( KnownSymbol h, GetHeadersFromHList rest, ToHttpApiData v) => GetHeaders' ( Header h v ': rest) Source # | |
|
Defined in Servant.API.ResponseHeaders Methods getHeaders' :: Headers ( Header h v ': rest) a -> [ Header0 ] |
|
| ( FromHttpApiData v, BuildHeadersTo xs, KnownSymbol h) => BuildHeadersTo ( Header h v ': xs) Source # | |
|
Defined in Servant.API.ResponseHeaders |
|
Type-level modifiers for
QueryParam
,
Header
and
ReqBody
.
Accessing information from the request
data CaptureAll (sym :: Symbol ) (a :: *) Source #
Capture all remaining values from the request path under a certain type
a
.
Example:
>>>-- GET /src/*>>>type MyAPI = "src" :> CaptureAll "segments" Text :> Get '[JSON] SourceFile
Instances
| ( ToHttpApiData v, HasLink sub) => HasLink ( CaptureAll sym v :> sub :: Type ) Source # | |
|
Defined in Servant.Links Associated Types type MkLink ( CaptureAll sym v :> sub) a Source # |
|
| type MkLink ( CaptureAll sym v :> sub :: Type ) a Source # | |
|
Defined in Servant.Links |
|
data Capture' (mods :: [*]) (sym :: Symbol ) (a :: *) Source #
Capture
which can be modified. For example with
Description
.
type Capture = Capture' '[] Source #
Capture a value from the request path under a certain type
a
.
Example:
>>>-- GET /books/:isbn>>>type MyApi = "books" :> Capture "isbn" Text :> Get '[JSON] Book
Capturing parts of the url path as parsed values:
and
Capture
CaptureAll
data Header' (mods :: [*]) (sym :: Symbol ) (a :: *) Source #
Instances
| ( KnownSymbol h, ToHttpApiData v) => AddHeader h v ( Headers (fst ': rest) a) ( Headers ( Header h v ': (fst ': rest)) a) Source # | |
|
Defined in Servant.API.ResponseHeaders Methods addOptionalHeader :: ResponseHeader h v -> Headers (fst ': rest) a -> Headers ( Header h v ': (fst ': rest)) a |
|
| HasResponseHeader h a ( Header h a ': rest) Source # | |
|
Defined in Servant.API.ResponseHeaders Methods hlistLookupHeader :: HList ( Header h a ': rest) -> ResponseHeader h a |
|
| HasLink sub => HasLink ( Header' mods sym a :> sub :: Type ) Source # | |
| ( KnownSymbol h, GetHeadersFromHList rest, ToHttpApiData v) => GetHeaders' ( Header h v ': rest) Source # | |
|
Defined in Servant.API.ResponseHeaders Methods getHeaders' :: Headers ( Header h v ': rest) a -> [ Header0 ] |
|
| ( FromHttpApiData v, BuildHeadersTo xs, KnownSymbol h) => BuildHeadersTo ( Header h v ': xs) Source # | |
|
Defined in Servant.API.ResponseHeaders |
|
| type MkLink ( Header' mods sym a :> sub :: Type ) r Source # | |
type Header = Header' '[ Optional , Strict ] Source #
Extract the given header's value as a value of type
a
.
I.e. header sent by client, parsed by server.
Example:
>>>newtype Referer = Referer Text deriving (Eq, Show)>>>>>>-- GET /view-my-referer>>>type MyApi = "view-my-referer" :> Header "from" Referer :> Get '[JSON] Referer
Retrieving specific headers from the request
data HttpVersion Source #
HTTP Version.
Note that the Show instance is intended merely for debugging.
Constructors
| HttpVersion | |
Instances
| Eq HttpVersion | |
|
Defined in Network.HTTP.Types.Version Methods (==) :: HttpVersion -> HttpVersion -> Bool Source # (/=) :: HttpVersion -> HttpVersion -> Bool Source # |
|
| Ord HttpVersion | |
|
Defined in Network.HTTP.Types.Version Methods compare :: HttpVersion -> HttpVersion -> Ordering Source # (<) :: HttpVersion -> HttpVersion -> Bool Source # (<=) :: HttpVersion -> HttpVersion -> Bool Source # (>) :: HttpVersion -> HttpVersion -> Bool Source # (>=) :: HttpVersion -> HttpVersion -> Bool Source # max :: HttpVersion -> HttpVersion -> HttpVersion Source # min :: HttpVersion -> HttpVersion -> HttpVersion Source # |
|
| Show HttpVersion | |
|
Defined in Network.HTTP.Types.Version |
|
| HasLink sub => HasLink ( HttpVersion :> sub :: Type ) Source # | |
|
Defined in Servant.Links Associated Types type MkLink ( HttpVersion :> sub) a Source # |
|
| type MkLink ( HttpVersion :> sub :: Type ) a Source # | |
|
Defined in Servant.Links |
|
Retrieving the HTTP version of the request
data QueryFlag (sym :: Symbol ) Source #
Lookup a potentially value-less query string parameter
with boolean semantics. If the param
sym
is there without any value,
or if it's there with value "true" or "1", it's interpreted as
True
.
Otherwise, it's interpreted as
False
.
Example:
>>>-- /books?published>>>type MyApi = "books" :> QueryFlag "published" :> Get '[JSON] [Book]
data QueryParams (sym :: Symbol ) (a :: *) Source #
Lookup the values associated to the
sym
query string parameter
and try to extract it as a value of type
[a]
. This is typically
meant to support query string parameters of the form
param[]=val1¶m[]=val2
and so on. Note that servant doesn't actually
require the
[]
s and will fetch the values just fine with
param=val1¶m=val2
, too.
Example:
>>>-- /books?authors[]=<author1>&authors[]=<author2>&...>>>type MyApi = "books" :> QueryParams "authors" Text :> Get '[JSON] [Book]
Instances
| ( KnownSymbol sym, ToHttpApiData v, HasLink sub) => HasLink ( QueryParams sym v :> sub :: Type ) Source # | |
|
Defined in Servant.Links Associated Types type MkLink ( QueryParams sym v :> sub) a Source # |
|
| type MkLink ( QueryParams sym v :> sub :: Type ) a Source # | |
|
Defined in Servant.Links |
|
data QueryParam' (mods :: [*]) (sym :: Symbol ) (a :: *) Source #
QueryParam
which can be
Required
,
Lenient
, or modified otherwise.
Instances
| ( KnownSymbol sym, ToHttpApiData v, HasLink sub, SBoolI ( FoldRequired mods)) => HasLink ( QueryParam' mods sym v :> sub :: Type ) Source # | |
|
Defined in Servant.Links Associated Types type MkLink ( QueryParam' mods sym v :> sub) a Source # |
|
| type MkLink ( QueryParam' mods sym v :> sub :: Type ) a Source # | |
|
Defined in Servant.Links
type
MkLink
(
QueryParam'
mods sym v
:>
sub ::
Type
) a =
If
(
FoldRequired
mods) v (
Maybe
v) ->
MkLink
sub a
|
|
type QueryParam = QueryParam' '[ Optional , Strict ] Source #
Lookup the value associated to the
sym
query string parameter
and try to extract it as a value of type
a
.
Example:
>>>-- /books?author=<author name>>>>type MyApi = "books" :> QueryParam "author" Text :> Get '[JSON] [Book]
Retrieving parameters from the query string of the
URI
:
QueryParam
data Fragment (a :: *) Source #
Document the URI fragment in API. Useful in combination with
Link
.
Example:
>>>-- /post#TRACKING>>>type MyApi = "post" :> Fragment Text :> Get '[JSON] Tracking
data ReqBody' (mods :: [*]) (contentTypes :: [*]) (a :: *) Source #
type ReqBody = ReqBody' '[ Required , Strict ] Source #
Extract the request body as a value of type
a
.
Example:
>>>-- POST /books>>>type MyApi = "books" :> ReqBody '[JSON] Book :> Post '[JSON] Book
Accessing the request body as a JSON-encoded type:
ReqBody
data RemoteHost Source #
Provides access to the host or IP address from which the HTTP request was sent.
Instances
| HasLink sub => HasLink ( RemoteHost :> sub :: Type ) Source # | |
|
Defined in Servant.Links Associated Types type MkLink ( RemoteHost :> sub) a Source # |
|
| type MkLink ( RemoteHost :> sub :: Type ) a Source # | |
|
Defined in Servant.Links |
|
Retrieving the IP of the client
Was this request made over an SSL connection?
Note that this value will not tell you if the client originally
made this request over SSL, but rather whether the current
connection is SSL. The distinction lies with reverse proxies.
In many cases, the client will connect to a load balancer over SSL,
but connect to the WAI handler without SSL. In such a case,
the handlers would get
NotSecure
, but from a user perspective,
there is a secure connection.
Constructors
| Secure |
the connection to the server is secure (HTTPS) |
| NotSecure |
the connection to the server is not secure (HTTP) |
Instances
| Eq IsSecure Source # | |
| Ord IsSecure Source # | |
|
Defined in Servant.API.IsSecure |
|
| Read IsSecure Source # | |
| Show IsSecure Source # | |
| Generic IsSecure Source # | |
| HasLink sub => HasLink ( IsSecure :> sub :: Type ) Source # | |
| type Rep IsSecure Source # | |
| type MkLink ( IsSecure :> sub :: Type ) a Source # | |
Is the request made through HTTPS?
type Vault = Vault RealWorld Source #
A persistent store for values of arbitrary types.
This variant is the simplest and creates keys in the
IO
monad.
See the module
Data.Vault.ST
if you want to use it with the
ST
monad instead.
Access the location for arbitrary data to be shared by applications and middleware
data WithNamedContext (name :: Symbol ) (subContext :: [*]) subApi Source #
WithNamedContext
names a specific tagged context to use for the
combinators in the API. (See also in
servant-server
,
Servant.Server.Context
.) For example:
type UseNamedContextAPI = WithNamedContext "myContext" '[String] (
ReqBody '[JSON] Int :> Get '[JSON] Int)
Both the
ReqBody
and
Get
combinators will use the
WithNamedContext
with
type tag "myContext" as their context.
Context
s are only relevant for
servant-server
.
For more information, see the tutorial.
Instances
| HasLink sub => HasLink ( WithNamedContext name context sub :: Type ) Source # | |
|
Defined in Servant.Links Associated Types type MkLink ( WithNamedContext name context sub) a Source # Methods toLink :: ( Link -> a) -> Proxy ( WithNamedContext name context sub) -> Link -> MkLink ( WithNamedContext name context sub) a Source # |
|
| type MkLink ( WithNamedContext name context sub :: Type ) a Source # | |
|
Defined in Servant.Links |
|
Access context entries in combinators in servant-server
Actual endpoints, distinguished by HTTP method
HTTP standard method (as defined by RFC 2616, and PATCH which is defined by RFC 5789).
Instances
class ReflectMethod a where Source #
Methods
reflectMethod :: Proxy a -> Method Source #
Instances
| ReflectMethod ' PATCH Source # | |
|
Defined in Servant.API.Verbs |
|
| ReflectMethod ' OPTIONS Source # | |
|
Defined in Servant.API.Verbs |
|
| ReflectMethod ' CONNECT Source # | |
|
Defined in Servant.API.Verbs |
|
| ReflectMethod ' TRACE Source # | |
|
Defined in Servant.API.Verbs |
|
| ReflectMethod ' DELETE Source # | |
|
Defined in Servant.API.Verbs |
|
| ReflectMethod ' PUT Source # | |
|
Defined in Servant.API.Verbs |
|
| ReflectMethod ' HEAD Source # | |
|
Defined in Servant.API.Verbs |
|
| ReflectMethod ' POST Source # | |
|
Defined in Servant.API.Verbs |
|
| ReflectMethod ' GET Source # | |
|
Defined in Servant.API.Verbs |
|
type PutNoContent = NoContentVerb ' PUT Source #
PUT
with 204 status code.
type PatchNoContent = NoContentVerb ' PATCH Source #
PATCH
with 204 status code.
type DeleteNoContent = NoContentVerb ' DELETE Source #
DELETE
with 204 status code.
type PostNoContent = NoContentVerb ' POST Source #
POST
with 204 status code.
type GetNoContent = NoContentVerb ' GET Source #
GET
with 204 status code.
data NoContentVerb (method :: k1) Source #
NoContentVerb
is a specific type to represent
NoContent
responses.
It does not require either a list of content types (because there's
no content) or a status code (because it should always be 204).
Instances
| HasLink ( NoContentVerb m :: Type ) Source # | |
|
Defined in Servant.Links Associated Types type MkLink ( NoContentVerb m) a Source # Methods toLink :: ( Link -> a) -> Proxy ( NoContentVerb m) -> Link -> MkLink ( NoContentVerb m) a Source # |
|
| Generic ( NoContentVerb method) Source # | |
|
Defined in Servant.API.Verbs Methods from :: NoContentVerb method -> Rep ( NoContentVerb method) x Source # to :: Rep ( NoContentVerb method) x -> NoContentVerb method Source # |
|
| type MkLink ( NoContentVerb m :: Type ) r Source # | |
|
Defined in Servant.Links |
|
| type Rep ( NoContentVerb method) Source # | |
|
Defined in Servant.API.Verbs |
|
data Verb (method :: k1) (statusCode :: Nat ) (contentTypes :: [*]) (a :: *) Source #
Verb
is a general type for representing HTTP verbs (a.k.a. methods). For
convenience, type synonyms for each verb with a 200 response code are
provided, but you are free to define your own:
>>>type Post204 contentTypes a = Verb 'POST 204 contentTypes a
Instances
| HasLink ( Verb m s ct a :: Type ) Source # | |
| Generic ( Verb method statusCode contentTypes a) Source # | |
|
Defined in Servant.API.Verbs |
|
| AtLeastOneFragment ( Verb m s ct typ) Source # |
If fragment appeared in API endpoint twice, compile-time error would be raised.
|
|
Defined in Servant.API.TypeLevel |
|
| type MkLink ( Verb m s ct a :: Type ) r Source # | |
|
Defined in Servant.Links |
|
| type Rep ( Verb method statusCode contentTypes a) Source # | |
type family Unique xs :: Constraint where ... Source #
data UVerb (method :: StdMethod ) (contentTypes :: [*]) (as :: [*]) Source #
A variant of
Verb
that can have any of a number of response values and status codes.
FUTUREWORK: it would be nice to make
Verb
a special case of
UVerb
, and only write
instances for
HasServer
etc. for the latter, getting them for the former for free.
Something like:
type Verb method statusCode contentTypes a = UVerb method contentTypes [WithStatus statusCode a]
Backwards compatibility is tricky, though: this type alias would mean people would have to
use
respond
instead of
pure
or
return
, so all old handlers would have to be rewritten.
newtype WithStatus (k :: Nat ) a Source #
A simple newtype wrapper that pairs a type with its status code. It implements all the content types that Servant ships with by default.
Constructors
| WithStatus a |
Instances
class KnownStatus ( StatusOf a) => HasStatus (a :: *) Source #
Instances
| HasStatus NoContent Source # |
If an API can respond with
|
| KnownStatus n => HasStatus ( WithStatus n a) Source # |
an instance of this typeclass assigns a HTTP status code to a return type Example: data NotFoundError = NotFoundError String
instance HasStatus NotFoundError where
type StatusOf NotFoundError = 404
You can also use the convience newtype wrapper
|
|
Defined in Servant.API.UVerb Associated Types type StatusOf ( WithStatus n a) :: Nat Source # |
|
Sub-APIs defined as records of routes
data NamedRoutes (api :: * -> *) Source #
Combinator for embedding a record of named routes into a Servant API type.
Instances
| ( HasLink ( ToServantApi routes), forall a. GLink routes a) => HasLink ( NamedRoutes routes :: Type ) Source # | |
|
Defined in Servant.Links Associated Types type MkLink ( NamedRoutes routes) a Source # Methods toLink :: ( Link -> a) -> Proxy ( NamedRoutes routes) -> Link -> MkLink ( NamedRoutes routes) a Source # |
|
| type MkLink ( NamedRoutes routes :: Type ) a Source # | |
|
Defined in Servant.Links |
|
class GServantProduct f Source #
Minimal complete definition
gtoServant, gfromServant
Instances
| GServantProduct ( K1 i c :: Type -> Type ) Source # | |
|
Defined in Servant.API.Generic Associated Types type GToServant ( K1 i c) Methods gtoServant :: K1 i c p -> GToServant ( K1 i c) gfromServant :: GToServant ( K1 i c) -> K1 i c p |
|
| ( GServantProduct l, GServantProduct r) => GServantProduct (l :*: r) Source # | |
|
Defined in Servant.API.Generic Associated Types type GToServant (l :*: r) Methods gtoServant :: (l :*: r) p -> GToServant (l :*: r) gfromServant :: GToServant (l :*: r) -> (l :*: r) p |
|
| GServantProduct f => GServantProduct ( M1 i c f) Source # | |
|
Defined in Servant.API.Generic Associated Types type GToServant ( M1 i c f) Methods gtoServant :: M1 i c f p -> GToServant ( M1 i c f) gfromServant :: GToServant ( M1 i c f) -> M1 i c f p |
|
A type that specifies that an API record contains an API definition. Only useful at type-level.
type ToServantApi routes = ToServant routes AsApi Source #
type ToServant routes mode = GToServant ( Rep (routes mode)) Source #
Turns a generic product type into a tree of
:<|>
combinators.
class GenericMode mode Source #
A class with a type family that applies an appropriate type family to the
api
parameter. For example,
AsApi
will leave
api
untouched, while
will produce
AsServerT
m
.
ServerT
api m
Instances
| GenericMode AsApi Source # | |
|
Defined in Servant.API.Generic |
|
| GenericMode ( AsLink a) Source # | |
|
Defined in Servant.Links |
|
type GenericServant routes mode = ( GenericMode mode, Generic (routes mode), GServantProduct ( Rep (routes mode))) Source #
A constraint alias, for work with
mode
and
routes
.
toServant :: GenericServant routes mode => routes mode -> ToServant routes mode Source #
See
ToServant
, but at value-level.
fromServant :: GenericServant routes mode => ToServant routes mode -> routes mode Source #
Inverse of
toServant
.
This can be used to turn
generated
values such as client functions into records.
You may need to provide a type signature for the output type (your record type).
genericApi :: GenericServant routes AsApi => Proxy routes -> Proxy ( ToServantApi routes) Source #
Get a
Proxy
of an API type.
Streaming endpoints, distinguished by HTTP method
data NetstringFraming Source #
The netstring framing strategy as defined by djb: http://cr.yp.to/proto/netstrings.txt
Any string of 8-bit bytes may be encoded as
[len]":"[string]","
. Here
[string]
is the string and
[len]
is a nonempty sequence of ASCII digits
giving the length of
[string]
in decimal. The ASCII digits are
30
for
0,
31
for 1, and so on up through
39
for 9. Extra zeros at the front
of
[len]
are prohibited:
[len]
begins with
30
exactly when
[string]
is empty.
For example, the string
"hello world!"
is encoded as
32 3a 68 65 6c 6c 6f 20 77 6f 72 6c 64 21 2c
,
i.e.,
"12:hello world!,"
.
The empty string is encoded as
"0:,"
.
Instances
| FramingUnrender NetstringFraming Source # | |
|
Defined in Servant.API.Stream Methods framingUnrender :: forall (m :: Type -> Type ) a. Monad m => Proxy NetstringFraming -> ( ByteString -> Either String a) -> SourceT m ByteString -> SourceT m a Source # |
|
| FramingRender NetstringFraming Source # | |
|
Defined in Servant.API.Stream Methods framingRender :: forall (m :: Type -> Type ) a. Monad m => Proxy NetstringFraming -> (a -> ByteString ) -> SourceT m a -> SourceT m ByteString Source # |
|
data NewlineFraming Source #
A simple framing strategy that has no header, and inserts a newline character after each frame. This assumes that it is used with a Content-Type that encodes without newlines (e.g. JSON).
Instances
| FramingUnrender NewlineFraming Source # | |
|
Defined in Servant.API.Stream Methods framingUnrender :: forall (m :: Type -> Type ) a. Monad m => Proxy NewlineFraming -> ( ByteString -> Either String a) -> SourceT m ByteString -> SourceT m a Source # |
|
| FramingRender NewlineFraming Source # | |
|
Defined in Servant.API.Stream Methods framingRender :: forall (m :: Type -> Type ) a. Monad m => Proxy NewlineFraming -> (a -> ByteString ) -> SourceT m a -> SourceT m ByteString Source # |
|
A framing strategy that does not do any framing at all, it just passes the input data This will be used most of the time with binary data, such as files
Instances
| FramingUnrender NoFraming Source # |
As
That works well when
|
|
Defined in Servant.API.Stream Methods framingUnrender :: forall (m :: Type -> Type ) a. Monad m => Proxy NoFraming -> ( ByteString -> Either String a) -> SourceT m ByteString -> SourceT m a Source # |
|
| FramingRender NoFraming Source # | |
|
Defined in Servant.API.Stream Methods framingRender :: forall (m :: Type -> Type ) a. Monad m => Proxy NoFraming -> (a -> ByteString ) -> SourceT m a -> SourceT m ByteString Source # |
|
class FramingUnrender strategy where Source #
The
FramingUnrender
class provides the logic for parsing a framing
strategy.
Methods
framingUnrender :: Monad m => Proxy strategy -> ( ByteString -> Either String a) -> SourceT m ByteString -> SourceT m a Source #
Instances
| FramingUnrender NetstringFraming Source # | |
|
Defined in Servant.API.Stream Methods framingUnrender :: forall (m :: Type -> Type ) a. Monad m => Proxy NetstringFraming -> ( ByteString -> Either String a) -> SourceT m ByteString -> SourceT m a Source # |
|
| FramingUnrender NewlineFraming Source # | |
|
Defined in Servant.API.Stream Methods framingUnrender :: forall (m :: Type -> Type ) a. Monad m => Proxy NewlineFraming -> ( ByteString -> Either String a) -> SourceT m ByteString -> SourceT m a Source # |
|
| FramingUnrender NoFraming Source # |
As
That works well when
|
|
Defined in Servant.API.Stream Methods framingUnrender :: forall (m :: Type -> Type ) a. Monad m => Proxy NoFraming -> ( ByteString -> Either String a) -> SourceT m ByteString -> SourceT m a Source # |
|
class FramingRender strategy where Source #
The
FramingRender
class provides the logic for emitting a framing strategy.
The strategy transforms a
into
SourceT
m a
,
therefore it can prepend, append and intercalate
framing
structure
around chunks.
SourceT
m
ByteString
Note:
as the
is generic, this is pure transformation.
Monad
m
Methods
framingRender :: Monad m => Proxy strategy -> (a -> ByteString ) -> SourceT m a -> SourceT m ByteString Source #
Instances
| FramingRender NetstringFraming Source # | |
|
Defined in Servant.API.Stream Methods framingRender :: forall (m :: Type -> Type ) a. Monad m => Proxy NetstringFraming -> (a -> ByteString ) -> SourceT m a -> SourceT m ByteString Source # |
|
| FramingRender NewlineFraming Source # | |
|
Defined in Servant.API.Stream Methods framingRender :: forall (m :: Type -> Type ) a. Monad m => Proxy NewlineFraming -> (a -> ByteString ) -> SourceT m a -> SourceT m ByteString Source # |
|
| FramingRender NoFraming Source # | |
|
Defined in Servant.API.Stream Methods framingRender :: forall (m :: Type -> Type ) a. Monad m => Proxy NoFraming -> (a -> ByteString ) -> SourceT m a -> SourceT m ByteString Source # |
|
class FromSourceIO chunk a | a -> chunk where Source #
FromSourceIO
is intended to be implemented for types such as Conduit,
Pipe, etc. By implementing this class, all such streaming abstractions can
be used directly on the client side for talking to streaming endpoints.
Methods
fromSourceIO :: SourceIO chunk -> a Source #
Instances
| MonadIO m => FromSourceIO a ( SourceT m a) Source # | |
|
Defined in Servant.API.Stream Methods fromSourceIO :: SourceIO a -> SourceT m a Source # |
|
class ToSourceIO chunk a | a -> chunk where Source #
ToSourceIO
is intended to be implemented for types such as Conduit, Pipe,
etc. By implementing this class, all such streaming abstractions can be used
directly as endpoints.
Methods
toSourceIO :: a -> SourceIO chunk Source #
Instances
| ToSourceIO a [a] Source # | |
|
Defined in Servant.API.Stream Methods toSourceIO :: [a] -> SourceIO a Source # |
|
| ToSourceIO a ( NonEmpty a) Source # | |
|
Defined in Servant.API.Stream Methods toSourceIO :: NonEmpty a -> SourceIO a Source # |
|
| SourceToSourceIO m => ToSourceIO chunk ( SourceT m chunk) Source # |
Relax to use auxiliary class, have m |
|
Defined in Servant.API.Stream Methods toSourceIO :: SourceT m chunk -> SourceIO chunk Source # |
|
data StreamBody' (mods :: [*]) (framing :: *) (contentType :: *) (a :: *) Source #
Instances
| HasLink sub => HasLink ( StreamBody' mods framing ct a :> sub :: Type ) Source # | |
|
Defined in Servant.Links Associated Types type MkLink ( StreamBody' mods framing ct a :> sub) a Source # |
|
| Generic ( StreamBody' mods framing contentType a) Source # | |
|
Defined in Servant.API.Stream Methods from :: StreamBody' mods framing contentType a -> Rep ( StreamBody' mods framing contentType a) x Source # to :: Rep ( StreamBody' mods framing contentType a) x -> StreamBody' mods framing contentType a Source # |
|
| type MkLink ( StreamBody' mods framing ct a :> sub :: Type ) r Source # | |
|
Defined in Servant.Links |
|
| type Rep ( StreamBody' mods framing contentType a) Source # | |
|
Defined in Servant.API.Stream |
|
type StreamBody = StreamBody' '[] Source #
A stream request body.
type StreamPost = Stream ' POST 200 Source #
data Stream (method :: k1) (status :: Nat ) (framing :: *) (contentType :: *) (a :: *) Source #
A Stream endpoint for a given method emits a stream of encoded values at a
given
Content-Type
, delimited by a
framing
strategy.
Type synonyms are provided for standard methods.
Instances
Authentication
data BasicAuthData Source #
A simple datatype to hold data required to decorate a request
Constructors
| BasicAuthData | |
|
Fields |
|
data BasicAuth (realm :: Symbol ) (userData :: *) Source #
Combinator for Basic Access Authentication .
- IMPORTANT*: Only use Basic Auth over HTTPS! Credentials are not hashed or encrypted. Note also that because the same credentials are sent on every request, Basic Auth is not as secure as some alternatives. Further, the implementation in servant-server does not protect against some types of timing attacks.
In Basic Auth, username and password are base64-encoded and transmitted via
the
Authorization
header. Handshakes are not required, making it
relatively efficient.
Endpoints description
data Description (sym :: Symbol ) Source #
Add more verbose description for (part of) API.
Example:
>>>:{type MyApi = Description "This comment is visible in multiple Servant interpretations \ \and can be really long if necessary. \ \Haskell multiline String support is not perfect \ \but it's still very readable." :> Get '[JSON] Book :}
Instances
| HasLink sub => HasLink ( Description s :> sub :: Type ) Source # | |
|
Defined in Servant.Links Associated Types type MkLink ( Description s :> sub) a Source # |
|
| type MkLink ( Description s :> sub :: Type ) a Source # | |
|
Defined in Servant.Links |
|
data Summary (sym :: Symbol ) Source #
Add a short summary for (part of) API.
Example:
>>>type MyApi = Summary "Get book by ISBN." :> "books" :> Capture "isbn" Text :> Get '[JSON] Book
Content Types
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 |
|
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
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] Int
Methods
mimeRender :: Proxy ctype -> a -> ByteString Source #
Instances
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 |
|
data OctetStream Source #
Instances
data FormUrlEncoded Source #
Instances
Instances
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 # |
|
Serializing and deserializing types based on
Accept
and
Content-Type
headers.
Response Headers
class HasResponseHeader h a headers Source #
Minimal complete definition
hlistLookupHeader
Instances
| HasResponseHeader h a rest => HasResponseHeader h a (first ': rest) Source # | |
|
Defined in Servant.API.ResponseHeaders Methods hlistLookupHeader :: HList (first ': rest) -> ResponseHeader h a |
|
| HasResponseHeader h a ( Header h a ': rest) Source # | |
|
Defined in Servant.API.ResponseHeaders Methods hlistLookupHeader :: HList ( Header h a ': rest) -> ResponseHeader h a |
|
class AddHeader h v orig new | h v orig -> new, new -> h, new -> v, new -> orig Source #
Minimal complete definition
addOptionalHeader
Instances
| ( KnownSymbol h, ToHttpApiData v, new ~ Headers '[ Header h v] a) => AddHeader h v a new Source # | |
|
Defined in Servant.API.ResponseHeaders Methods addOptionalHeader :: ResponseHeader h v -> a -> new |
|
| ( KnownSymbol h, ToHttpApiData v) => AddHeader h v ( Headers (fst ': rest) a) ( Headers ( Header h v ': (fst ': rest)) a) Source # | |
|
Defined in Servant.API.ResponseHeaders Methods addOptionalHeader :: ResponseHeader h v -> Headers (fst ': rest) a -> Headers ( Header h v ': (fst ': rest)) a |
|
class GetHeaders ls where Source #
Methods
getHeaders :: ls -> [ Header ] Source #
Instances
| GetHeadersFromHList hs => GetHeaders ( HList hs) Source # | |
|
Defined in Servant.API.ResponseHeaders Methods getHeaders :: HList hs -> [ Header ] Source # |
|
| GetHeaders' hs => GetHeaders ( Headers hs a) Source # | |
|
Defined in Servant.API.ResponseHeaders Methods getHeaders :: Headers hs a -> [ Header ] Source # |
|
class BuildHeadersTo hs where Source #
Methods
buildHeadersTo :: [ Header ] -> HList hs Source #
Note: if there are multiple occurrences of a header in the argument, the values are interspersed with commas before deserialization (see RFC2616 Sec 4.2 )
Instances
| BuildHeadersTo ('[] :: [ Type ]) Source # | |
|
Defined in Servant.API.ResponseHeaders Methods buildHeadersTo :: [ Header ] -> HList '[] Source # |
|
| ( FromHttpApiData v, BuildHeadersTo xs, KnownSymbol h) => BuildHeadersTo ( Header h v ': xs) Source # | |
|
Defined in Servant.API.ResponseHeaders |
|
Instances
| NFDataHList xs => NFData ( HList xs) Source # | |
|
Defined in Servant.API.ResponseHeaders |
|
| GetHeadersFromHList hs => GetHeaders ( HList hs) Source # | |
|
Defined in Servant.API.ResponseHeaders Methods getHeaders :: HList hs -> [ Header ] Source # |
|
data ResponseHeader (sym :: Symbol ) a Source #
Constructors
| Header a | |
| MissingHeader | |
| UndecodableHeader ByteString |
Instances
| Functor ( ResponseHeader sym) Source # | |
|
Defined in Servant.API.ResponseHeaders Methods fmap :: (a -> b) -> ResponseHeader sym a -> ResponseHeader sym b Source # (<$) :: a -> ResponseHeader sym b -> ResponseHeader sym a Source # |
|
| Eq a => Eq ( ResponseHeader sym a) Source # | |
|
Defined in Servant.API.ResponseHeaders Methods (==) :: ResponseHeader sym a -> ResponseHeader sym a -> Bool Source # (/=) :: ResponseHeader sym a -> ResponseHeader sym a -> Bool Source # |
|
| Show a => Show ( ResponseHeader sym a) Source # | |
|
Defined in Servant.API.ResponseHeaders |
|
| NFData a => NFData ( ResponseHeader sym a) Source # | |
|
Defined in Servant.API.ResponseHeaders Methods rnf :: ResponseHeader sym a -> () Source # |
|
Response Header objects. You should never need to construct one directly.
Instead, use
addOptionalHeader
.
Constructors
| Headers | |
|
Fields
|
|
Instances
| ( KnownSymbol h, ToHttpApiData v) => AddHeader h v ( Headers (fst ': rest) a) ( Headers ( Header h v ': (fst ': rest)) a) Source # | |
|
Defined in Servant.API.ResponseHeaders Methods addOptionalHeader :: ResponseHeader h v -> Headers (fst ': rest) a -> Headers ( Header h v ': (fst ': rest)) a |
|
| Functor ( Headers ls) Source # | |
| (NFDataHList ls, NFData a) => NFData ( Headers ls a) Source # | |
|
Defined in Servant.API.ResponseHeaders |
|
| GetHeaders' hs => GetHeaders ( Headers hs a) Source # | |
|
Defined in Servant.API.ResponseHeaders Methods getHeaders :: Headers hs a -> [ Header ] Source # |
|
addHeader :: AddHeader h v orig new => v -> orig -> new Source #
addHeader
adds a header to a response. Note that it changes the type of
the value in the following ways:
- A simple value is wrapped in "Headers '[hdr]":
>>>let example1 = addHeader 5 "hi" :: Headers '[Header "someheader" Int] String;>>>getHeaders example1[("someheader","5")]
- A value that already has a header has its new header *prepended* to the existing list:
>>>let example1 = addHeader 5 "hi" :: Headers '[Header "someheader" Int] String;>>>let example2 = addHeader True example1 :: Headers '[Header "1st" Bool, Header "someheader" Int] String>>>getHeaders example2[("1st","true"),("someheader","5")]
Note that while in your handlers type annotations are not required, since the type can be inferred from the API type, in other cases you may find yourself needing to add annotations.
noHeader :: AddHeader h v orig new => orig -> new Source #
Deliberately do not add a header to a value.
>>>let example1 = noHeader "hi" :: Headers '[Header "someheader" Int] String>>>getHeaders example1[]
lookupResponseHeader :: HasResponseHeader h a headers => Headers headers r -> ResponseHeader h a Source #
Look up a specific ResponseHeader, without having to know what position it is in the HList.
>>>let example1 = addHeader 5 "hi" :: Headers '[Header "someheader" Int] String>>>let example2 = addHeader True example1 :: Headers '[Header "1st" Bool, Header "someheader" Int] String>>>lookupResponseHeader example2 :: ResponseHeader "someheader" IntHeader 5
>>>lookupResponseHeader example2 :: ResponseHeader "1st" BoolHeader True
Usage of this function relies on an explicit type annotation of the header to be looked up. This can be done with type annotations on the result, or with an explicit type application. In this example, the type of header value is determined by the type-inference, we only specify the name of the header:
>>>:set -XTypeApplications>>>case lookupResponseHeader @"1st" example2 of { Header b -> b ; _ -> False }True
Since: 0.15
Untyped endpoints
Endpoint for plugging in your own Wai
Application
s.
The given
Application
will get the request as received by the server, potentially with
a modified (stripped)
pathInfo
if the
Application
is being routed with
:>
.
In addition to just letting you plug in your existing WAI
Application
s,
this can also be used with functions from
Servant.Server.StaticFiles
to serve static files stored in a particular directory on your filesystem
Plugging in a wai
Application
, serving directories
FromHttpApiData and ToHttpApiData
class ToHttpApiData a where Source #
Convert value to HTTP API data.
WARNING
: Do not derive this using
DeriveAnyClass
as the generated
instance will loop indefinitely.
Minimal complete definition
Methods
toUrlPiece :: a -> Text Source #
Convert to URL path piece.
toEncodedUrlPiece :: a -> Builder Source #
Convert to a URL path piece, making sure to encode any special chars.
The default definition uses
encodePathSegmentsRelative
,
but this may be overriden with a more efficient version.
toHeader :: a -> ByteString Source #
Convert to HTTP header value.
toQueryParam :: a -> Text Source #
Convert to query param value.
Instances
class FromHttpApiData a where Source #
Parse value from HTTP API data.
WARNING
: Do not derive this using
DeriveAnyClass
as the generated
instance will loop indefinitely.
Minimal complete definition
Methods
parseUrlPiece :: Text -> Either Text a Source #
Parse URL path piece.
parseHeader :: ByteString -> Either Text a Source #
Parse HTTP header value.
parseQueryParam :: Text -> Either Text a Source #
Parse query param value.
Instances
Classes and instances for types that can be converted to and from HTTP API data.
Experimental modules
data AuthProtect (tag :: k) Source #
A generalized Authentication combinator. Use this if you have a non-standard authentication technique.
NOTE: THIS API IS EXPERIMENTAL AND SUBJECT TO CHANGE.
Instances
| HasLink sub => HasLink ( AuthProtect tag :> sub :: Type ) Source # | |
|
Defined in Servant.Links Associated Types type MkLink ( AuthProtect tag :> sub) a Source # |
|
| type MkLink ( AuthProtect tag :> sub :: Type ) a Source # | |
|
Defined in Servant.Links |
|
General Authentication
Links
Represents a general universal resource identifier using its component parts.
For example, for the URI
foo://anonymous@www.haskell.org:42/ghc?query#frag
the components are:
Constructors
| URI | |
Instances
| Eq URI | |
| Data URI | |
|
Defined in Network.URI Methods gfoldl :: ( forall d b. Data d => c (d -> b) -> d -> c b) -> ( forall g. g -> c g) -> URI -> c URI Source # gunfold :: ( forall b r. Data b => c (b -> r) -> c r) -> ( forall r. r -> c r) -> Constr -> c URI Source # toConstr :: URI -> Constr Source # dataTypeOf :: URI -> DataType Source # dataCast1 :: Typeable t => ( forall d. Data d => c (t d)) -> Maybe (c URI ) Source # dataCast2 :: Typeable t => ( forall d e. ( Data d, Data e) => c (t d e)) -> Maybe (c URI ) Source # gmapT :: ( forall b. Data b => b -> b) -> URI -> URI Source # gmapQl :: (r -> r' -> r) -> r -> ( forall d. Data d => d -> r') -> URI -> r Source # gmapQr :: forall r r'. (r' -> r -> r) -> r -> ( forall d. Data d => d -> r') -> URI -> r Source # gmapQ :: ( forall d. Data d => d -> u) -> URI -> [u] Source # gmapQi :: Int -> ( forall d. Data d => d -> u) -> URI -> u Source # gmapM :: Monad m => ( forall d. Data d => d -> m d) -> URI -> m URI Source # gmapMp :: MonadPlus m => ( forall d. Data d => d -> m d) -> URI -> m URI Source # gmapMo :: MonadPlus m => ( forall d. Data d => d -> m d) -> URI -> m URI Source # |
|
| Ord URI | |
| Show URI | |
| Generic URI | |
| NFData URI | |
|
Defined in Network.URI |
|
| Lift URI | |
| type Rep URI | |
|
Defined in Network.URI
type
Rep
URI
=
D1
('
MetaData
"URI" "Network.URI" "network-uri-2.6.4.2-C9r4xjh6a7gFcwQqmO7bU3" '
False
) (
C1
('
MetaCons
"URI" '
PrefixI
'
True
) ((
S1
('
MetaSel
('
Just
"uriScheme") '
NoSourceUnpackedness
'
NoSourceStrictness
'
DecidedLazy
) (
Rec0
String
)
:*:
S1
('
MetaSel
('
Just
"uriAuthority") '
NoSourceUnpackedness
'
NoSourceStrictness
'
DecidedLazy
) (
Rec0
(
Maybe
URIAuth
)))
:*:
(
S1
('
MetaSel
('
Just
"uriPath") '
NoSourceUnpackedness
'
NoSourceStrictness
'
DecidedLazy
) (
Rec0
String
)
:*:
(
S1
('
MetaSel
('
Just
"uriQuery") '
NoSourceUnpackedness
'
NoSourceStrictness
'
DecidedLazy
) (
Rec0
String
)
:*:
S1
('
MetaSel
('
Just
"uriFragment") '
NoSourceUnpackedness
'
NoSourceStrictness
'
DecidedLazy
) (
Rec0
String
)))))
|
|
type family IsElem endpoint api :: Constraint where ... Source #
Closed type family, check if
endpoint
is within
api
.
Uses
if it exhausts all other options.
IsElem'
>>>ok (Proxy :: Proxy (IsElem ("hello" :> Get '[JSON] Int) SampleAPI))OK
>>>ok (Proxy :: Proxy (IsElem ("bye" :> Get '[JSON] Int) SampleAPI))... ... Could not ... ...
An endpoint is considered within an api even if it is missing combinators that don't affect the URL:
>>>ok (Proxy :: Proxy (IsElem (Get '[JSON] Int) (Header "h" Bool :> Get '[JSON] Int)))OK
>>>ok (Proxy :: Proxy (IsElem (Get '[JSON] Int) (ReqBody '[JSON] Bool :> Get '[JSON] Int)))OK
-
N.B.:*
IsElem a bcan be seen as capturing the notion of whether the URL represented byawould match the URL represented byb, *not* whether a request represented byamatches the endpoints servingb(for the latter, useIsIn).
Equations
| IsElem e (sa :<|> sb) = Or ( IsElem e sa) ( IsElem e sb) | |
| IsElem (e :> sa) (e :> sb) = IsElem sa sb | |
| IsElem sa ( Header sym x :> sb) = IsElem sa sb | |
| IsElem sa ( ReqBody y x :> sb) = IsElem sa sb | |
| IsElem ( CaptureAll z y :> sa) ( CaptureAll x y :> sb) = IsElem sa sb | |
| IsElem ( Capture z y :> sa) ( Capture x y :> sb) = IsElem sa sb | |
| IsElem sa ( QueryParam x y :> sb) = IsElem sa sb | |
| IsElem sa ( QueryParams x y :> sb) = IsElem sa sb | |
| IsElem sa ( QueryFlag x :> sb) = IsElem sa sb | |
| IsElem sa ( Fragment x :> sb) = IsElem sa sb | |
| IsElem ( Verb m s ct typ) ( Verb m s ct' typ) = IsSubList ct ct' | |
| IsElem e e = () | |
| IsElem e a = IsElem' e a |
type family IsElem' a s :: Constraint Source #
You may use this type family to tell the type checker that your custom
type may be skipped as part of a link. This is useful for things like
that are optional in a URI and do not affect them if they are
omitted.
QueryParam
>>>data CustomThing>>>type instance IsElem' e (CustomThing :> s) = IsElem e s
Note that
is called, which will mutually recurse back to
IsElem
if it exhausts all other options again.
IsElem'
Once you have written a
HasLink
instance for
CustomThing
you are ready to go.
class HasLink endpoint where Source #
Construct a toLink for an endpoint.
Methods
Instances
A safe link datatype.
The only way of constructing a
Link
is using
safeLink
, which means any
Link
is guaranteed to be part of the mentioned API.
Instances
| Show Link Source # | |
| ToHttpApiData Link Source # | |
|
Defined in Servant.Links Methods toUrlPiece :: Link -> Text Source # toEncodedUrlPiece :: Link -> Builder Source # toHeader :: Link -> ByteString Source # toQueryParam :: Link -> Text Source # |
|
Arguments
| :: forall endpoint api. ( IsElem endpoint api, HasLink endpoint) | |
| => Proxy api |
The whole API that this endpoint is a part of |
| -> Proxy endpoint |
The API endpoint you would like to point to |
| -> MkLink endpoint Link |
Create a valid (by construction) relative URI with query params.
This function will only typecheck if
endpoint
is part of the API
api
Type-safe internal URIs
Re-exports
type family If (cond :: Bool ) (tru :: k) (fls :: k) :: k where ... Source #
Type-level
If
.
If True a b
==>
a
;
If False a b
==>
b
data SBool (b :: Bool ) where Source #
Instances
| Eq ( SBool b) |
Since: singleton-bool-0.1.5 |
| Ord ( SBool b) |
Since: singleton-bool-0.1.5 |
|
Defined in Data.Singletons.Bool |
|
| Show ( SBool b) |
Since: singleton-bool-0.1.5 |