| Safe Haskell | Safe-Inferred |
|---|---|
| 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 :: Type)
- data a :<|> b = a :<|> b
- data EmptyAPI = EmptyAPI
- data Strict
- data Lenient
- data Optional
- data Required
- type Capture = Capture' '[]
- data Capture' (mods :: [Type]) (sym :: Symbol) (a :: Type)
- data CaptureAll (sym :: Symbol) (a :: Type)
- type Header = Header' '[Optional, Strict]
- data Header' (mods :: [Type]) (sym :: Symbol) (a :: Type)
- data HttpVersion = HttpVersion {}
- type QueryParam = QueryParam' '[Optional, Strict]
- data QueryFlag (sym :: Symbol)
- data QueryParam' (mods :: [Type]) (sym :: Symbol) (a :: Type)
- data QueryParams (sym :: Symbol) (a :: Type)
- data QueryString
- data DeepQuery (sym :: Symbol) (a :: Type)
- data Fragment (a :: Type)
- type ReqBody = ReqBody' '[Required, Strict]
- data ReqBody' (mods :: [Type]) (contentTypes :: [Type]) (a :: Type)
- data RemoteHost
- data IsSecure
- type Vault = Vault RealWorld
- data WithNamedContext (name :: Symbol) (subContext :: [Type]) subApi
- data WithResource res
- type Get = Verb 'GET 200
- type Put = Verb 'PUT 200
- data StdMethod
- type Delete = Verb 'DELETE 200
- type DeleteAccepted = Verb 'DELETE 202
- type DeleteNoContent = NoContentVerb 'DELETE
- type DeleteNonAuthoritative = Verb 'DELETE 203
- type GetAccepted = Verb 'GET 202
- type GetNoContent = NoContentVerb 'GET
- type GetNonAuthoritative = Verb 'GET 203
- type GetPartialContent = Verb 'GET 206
- type GetResetContent = Verb 'GET 205
- data NoContentVerb (method :: k1)
- type Patch = Verb 'PATCH 200
- type PatchAccepted = Verb 'PATCH 202
- type PatchNoContent = NoContentVerb 'PATCH
- type PatchNonAuthoritative = Verb 'PATCH 203
- type Post = Verb 'POST 200
- type PostAccepted = Verb 'POST 202
- type PostCreated = Verb 'POST 201
- type PostNoContent = NoContentVerb 'POST
- type PostNonAuthoritative = Verb 'POST 203
- type PostResetContent = Verb 'POST 205
- type PutAccepted = Verb 'PUT 202
- type PutCreated = Verb 'PUT 201
- type PutNoContent = NoContentVerb 'PUT
- type PutNonAuthoritative = Verb 'PUT 203
- class ReflectMethod a where
- reflectMethod :: Proxy a -> Method
- data Verb (method :: k1) (statusCode :: Nat) (contentTypes :: [Type]) (a :: Type)
- type family Unique xs :: Constraint where ...
- type Union = NS I
- data UVerb (method :: StdMethod) (contentTypes :: [Type]) (as :: [Type])
- class KnownStatus (StatusOf a) => HasStatus (a :: Type) where
- type IsMember (a :: u) (as :: [u]) = (Unique as, CheckElemIsMember a as, UElem a as)
- type family Statuses (as :: [Type]) :: [Nat]
- type family Statuses (as :: [Type]) :: [Nat]
- newtype WithStatus (k :: Nat) a = WithStatus a
- inject :: UElem x xs => f x -> NS f xs
- statusOf :: forall a proxy. HasStatus a => proxy a -> Status
- data NamedRoutes (api :: Type -> Type)
- class GenericMode mode where
- data AsApi
- class GServantProduct f
- type GenericServant routes mode = (GenericMode mode, Generic (routes mode), GServantProduct (Rep (routes mode)))
- type ToServant routes mode = GToServant (Rep (routes mode))
- type ToServantApi routes = ToServant routes AsApi
- fromServant :: GenericServant routes mode => ToServant routes mode -> routes mode
- genericApi :: GenericServant routes AsApi => Proxy routes -> Proxy (ToServantApi routes)
- toServant :: GenericServant routes mode => routes mode -> ToServant routes mode
- data Stream (method :: k1) (status :: Nat) (framing :: Type) (contentType :: Type) (a :: Type)
- class FramingRender strategy where
- framingRender :: Monad m => Proxy strategy -> (a -> ByteString) -> SourceT m a -> SourceT m ByteString
- class FramingUnrender strategy where
- framingUnrender :: Monad m => Proxy strategy -> (ByteString -> Either String a) -> SourceT m ByteString -> SourceT m a
- class FromSourceIO chunk a | a -> chunk where
- fromSourceIO :: SourceIO chunk -> IO a
- data NetstringFraming
- data NewlineFraming
- data NoFraming
- type SourceIO = SourceT IO
- type StreamBody = StreamBody' '[]
- data StreamBody' (mods :: [Type]) (framing :: Type) (contentType :: Type) (a :: Type)
- type StreamGet = Stream 'GET 200
- type StreamPost = Stream 'POST 200
- class ToSourceIO chunk a | a -> chunk where
- toSourceIO :: a -> SourceIO chunk
- data BasicAuth (realm :: Symbol) (userData :: Type)
- data BasicAuthData = BasicAuthData {}
- data Description (sym :: Symbol)
- data Summary (sym :: Symbol)
- class Accept ctype where
- contentType :: Proxy ctype -> MediaType
- contentTypes :: Proxy ctype -> NonEmpty MediaType
- data FormUrlEncoded
- data JSON
- 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
- data OctetStream
- data PlainText
- class AddHeader (mods :: [Type]) h v orig new | mods h v orig -> new, new -> mods, new -> h, new -> v, new -> orig
- class BuildHeadersTo hs where
- buildHeadersTo :: [Header] -> HList hs
- class GetHeaders ls where
- getHeaders :: ls -> [Header]
- data HList a where
- class HasResponseHeader h a headers
- data Headers ls a = Headers {
- getResponse :: a
- getHeadersHList :: HList ls
- data ResponseHeader (sym :: Symbol) a
- addHeader :: AddHeader '[Optional, Strict] h v orig new => v -> orig -> new
- addHeader' :: AddHeader mods h v orig new => v -> orig -> new
- lookupResponseHeader :: HasResponseHeader h a headers => Headers headers r -> ResponseHeader h a
- noHeader :: AddHeader '[Optional, Strict] h v orig new => orig -> new
- noHeader' :: AddHeader mods h v orig new => orig -> new
- data Raw
- data RawM
- class FromHttpApiData a where
- parseUrlPiece :: Text -> Either Text a
- parseHeader :: ByteString -> Either Text a
- parseQueryParam :: Text -> Either Text a
- class ToHttpApiData a where
- toUrlPiece :: a -> Text
- toEncodedUrlPiece :: a -> Builder
- toHeader :: a -> ByteString
- toQueryParam :: a -> Text
- toEncodedQueryParam :: a -> Builder
- data AuthProtect (tag :: k)
- data URI = URI {}
- class HasLink endpoint where
- type family IsElem endpoint api :: Constraint where ...
- type family IsElem' a s :: Constraint
- 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 :: Type) 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
| Bifoldable (:<|>) Source # | |
| Bifunctor (:<|>) Source # | |
| Bitraversable (:<|>) Source # | |
Defined in Servant.API.Alternative Methods bitraverse :: Applicative f => (a -> f c) -> (b -> f d) -> (a :<|> b) -> f (c :<|> d) # | |
| Biapplicative (:<|>) Source # | |
| (HasLink a, HasLink b) => HasLink (a :<|> b :: Type) Source # | |
| Foldable ((:<|>) a) Source # | |
Defined in Servant.API.Alternative Methods fold :: Monoid m => (a :<|> m) -> m # foldMap :: Monoid m => (a0 -> m) -> (a :<|> a0) -> m # foldMap' :: Monoid m => (a0 -> m) -> (a :<|> a0) -> m # foldr :: (a0 -> b -> b) -> b -> (a :<|> a0) -> b # foldr' :: (a0 -> b -> b) -> b -> (a :<|> a0) -> b # foldl :: (b -> a0 -> b) -> b -> (a :<|> a0) -> b # foldl' :: (b -> a0 -> b) -> b -> (a :<|> a0) -> b # foldr1 :: (a0 -> a0 -> a0) -> (a :<|> a0) -> a0 # foldl1 :: (a0 -> a0 -> a0) -> (a :<|> a0) -> a0 # toList :: (a :<|> a0) -> [a0] # length :: (a :<|> a0) -> Int # elem :: Eq a0 => a0 -> (a :<|> a0) -> Bool # maximum :: Ord a0 => (a :<|> a0) -> a0 # minimum :: Ord a0 => (a :<|> a0) -> a0 # | |
| Traversable ((:<|>) a) Source # | |
| Functor ((:<|>) a) Source # | |
| (Monoid a, Monoid b) => Monoid (a :<|> b) Source # | |
| (Semigroup a, Semigroup b) => Semigroup (a :<|> b) Source # | |
| (Bounded a, Bounded b) => Bounded (a :<|> b) Source # | |
| (Show a, Show b) => Show (a :<|> b) Source # | |
| (Eq a, Eq b) => Eq (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 | |
| Show EmptyAPI Source # | |
| Eq EmptyAPI Source # | |
| HasLink EmptyAPI Source # | |
| type MkLink EmptyAPI a Source # | |
Defined in Servant.Links | |
Type-level combinator for an empty API: EmptyAPI
Type-level modifiers for QueryParam, ResponseHeader and ReqBody.
Accessing information from the request
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
data Capture' (mods :: [Type]) (sym :: Symbol) (a :: Type) Source #
Capture which can be modified. For example with Description.
data CaptureAll (sym :: Symbol) (a :: Type) 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 | |
Capturing parts of the url path as parsed values: CaptureCaptureAll
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
data Header' (mods :: [Type]) (sym :: Symbol) (a :: Type) Source #
Instances
| (KnownSymbol h, ToHttpApiData v) => AddHeader mods h v (Headers (fst ': rest) a) (Headers (Header' mods h v ': (fst ': rest)) a) Source # | |
Defined in Servant.API.ResponseHeaders Methods addOptionalHeader :: ResponseHeader h v -> Headers (fst ': rest) a -> Headers (Header' mods h v ': (fst ': rest)) a | |
| HasResponseHeader h a (Header' mods h a ': rest) Source # | |
Defined in Servant.API.ResponseHeaders Methods hlistLookupHeader :: HList (Header' mods h a ': rest) -> ResponseHeader h a | |
| HasLink sub => HasLink (Header' mods sym a :> sub :: Type) Source # | |
| (FromHttpApiData v, BuildHeadersTo xs, KnownSymbol h) => BuildHeadersTo (Header' mods h v ': xs) Source # | |
Defined in Servant.API.ResponseHeaders | |
| (KnownSymbol h, GetHeadersFromHList rest, ToHttpApiData v) => GetHeaders' (Header' mods h v ': rest) Source # | |
Defined in Servant.API.ResponseHeaders Methods getHeaders' :: Headers (Header' mods h v ': rest) a -> [Header] | |
| type MkLink (Header' mods sym a :> sub :: Type) r Source # | |
Retrieving specific headers from the request
data HttpVersion Source #
HTTP Version.
Note that the Show instance is intended merely for debugging.
Constructors
| HttpVersion | |
Instances
Retrieving the HTTP version of the request
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]
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 QueryParam' (mods :: [Type]) (sym :: Symbol) (a :: Type) 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 | |
data QueryParams (sym :: Symbol) (a :: Type) 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 | |
Retrieving parameters from the query string of the URI: QueryParam
data QueryString Source #
Extract the whole query string from a request. This is useful for query strings
containing dynamic parameter names. For query strings with static parameter names,
QueryParam is more suited.
Example:
>>>-- /books?author=<author name>&year=<book year>>>>type MyApi = "books" :> QueryString :> Get '[JSON] [Book]
data DeepQuery (sym :: Symbol) (a :: Type) Source #
Extract an deep object from a query string.
Example:
>>>-- /books?filter[author][name]=<author name>&filter[year]=<book year>>>>type MyApi = "books" :> DeepQuery "filter" BookQuery :> Get '[JSON] [Book]
Retrieving the complete query string of the URI: QueryString
data Fragment (a :: Type) Source #
Document the URI fragment in API. Useful in combination with Link.
Example:
>>>-- /post#TRACKING>>>type MyApi = "post" :> Fragment Text :> Get '[JSON] Tracking
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
data ReqBody' (mods :: [Type]) (contentTypes :: [Type]) (a :: Type) Source #
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) |
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 :: [Type]) 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.
Contexts 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
data WithResource res Source #
Instances
| HasLink sub => HasLink (WithResource res :> sub :: Type) Source # | |
Defined in Servant.Links Associated Types type MkLink (WithResource res :> sub) a Source # | |
| type MkLink (WithResource res :> sub :: Type) a Source # | |
Defined in Servant.Links | |
Access a managed resource scoped to a single request
Actual endpoints, distinguished by HTTP method
HTTP standard method (as defined by RFC 2616, and PATCH which is defined by RFC 5789).
Since: http-types-0.2.0
Instances
type DeleteNoContent = NoContentVerb 'DELETE Source #
DELETE 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 Associated Types type Rep (NoContentVerb method) :: Type -> Type # Methods from :: NoContentVerb method -> Rep (NoContentVerb method) x # to :: Rep (NoContentVerb method) x -> NoContentVerb method # | |
| type MkLink (NoContentVerb m :: Type) r Source # | |
Defined in Servant.Links | |
| type Rep (NoContentVerb method) Source # | |
Defined in Servant.API.Verbs | |
type PatchNoContent = NoContentVerb 'PATCH Source #
PATCH with 204 status code.
type PostNoContent = NoContentVerb 'POST Source #
POST with 204 status code.
type PutNoContent = NoContentVerb 'PUT Source #
PUT with 204 status code.
class ReflectMethod a where Source #
Methods
reflectMethod :: Proxy a -> Method Source #
Instances
| ReflectMethod 'CONNECT Source # | |
Defined in Servant.API.Verbs | |
| ReflectMethod 'DELETE Source # | |
Defined in Servant.API.Verbs | |
| ReflectMethod 'GET Source # | |
Defined in Servant.API.Verbs | |
| ReflectMethod 'HEAD Source # | |
Defined in Servant.API.Verbs | |
| ReflectMethod 'OPTIONS Source # | |
Defined in Servant.API.Verbs | |
| ReflectMethod 'PATCH Source # | |
Defined in Servant.API.Verbs | |
| ReflectMethod 'POST Source # | |
Defined in Servant.API.Verbs | |
| ReflectMethod 'PUT Source # | |
Defined in Servant.API.Verbs | |
| ReflectMethod 'TRACE Source # | |
Defined in Servant.API.Verbs | |
data Verb (method :: k1) (statusCode :: Nat) (contentTypes :: [Type]) (a :: Type) 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 | |
| AtMostOneFragment (Verb m s ct typ) Source # | |
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 #
Check whether all values in a type-level list are distinct. This will throw a nice error if there are any duplicate elements in the list.
data UVerb (method :: StdMethod) (contentTypes :: [Type]) (as :: [Type]) 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.
class KnownStatus (StatusOf a) => HasStatus (a :: Type) Source #
Instances
| HasStatus NoContent Source # | If an API can respond with |
| HasStatus a => HasStatus (Headers ls a) Source # | |
| 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 # | |
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
Sub-APIs defined as records of routes
data NamedRoutes (api :: Type -> Type) Source #
Combinator for embedding a record of named routes into a Servant API type.
Instances
| (HasLink (ToServantApi routes), forall a. GLink routes a, ErrorIfNoGeneric routes) => 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 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
AsServerT mServerT api m
Instances
| GenericMode AsApi Source # | |
Defined in Servant.API.Generic | |
| GenericMode (AsLink a :: Type) Source # | |
Defined in Servant.Links | |
A type that specifies that an API record contains an API definition. Only useful at type-level.
class GServantProduct f Source #
Minimal complete definition
gtoServant, gfromServant
Instances
| (GServantProduct l, GServantProduct r) => GServantProduct (l :*: r :: k -> Type) Source # | |
Defined in Servant.API.Generic Associated Types type GToServant (l :*: r) Methods gtoServant :: forall (p :: k0). (l :*: r) p -> GToServant (l :*: r) gfromServant :: forall (p :: k0). GToServant (l :*: r) -> (l :*: r) p | |
| GServantProduct (K1 i c :: k -> Type) Source # | |
Defined in Servant.API.Generic Associated Types type GToServant (K1 i c) Methods gtoServant :: forall (p :: k0). K1 i c p -> GToServant (K1 i c) gfromServant :: forall (p :: k0). GToServant (K1 i c) -> K1 i c p | |
| GServantProduct f => GServantProduct (M1 i c f :: k -> Type) Source # | |
Defined in Servant.API.Generic Associated Types type GToServant (M1 i c f) Methods gtoServant :: forall (p :: k0). M1 i c f p -> GToServant (M1 i c f) gfromServant :: forall (p :: k0). GToServant (M1 i c f) -> M1 i c f p | |
type GenericServant routes mode = (GenericMode mode, Generic (routes mode), GServantProduct (Rep (routes mode))) Source #
A constraint alias, for work with mode and routes.
type ToServant routes mode = GToServant (Rep (routes mode)) Source #
Turns a generic product type into a tree of :<|> combinators.
type ToServantApi routes = ToServant routes AsApi Source #
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.
toServant :: GenericServant routes mode => routes mode -> ToServant routes mode Source #
See ToServant, but at value-level.
Streaming endpoints, distinguished by HTTP method
data Stream (method :: k1) (status :: Nat) (framing :: Type) (contentType :: Type) (a :: Type) 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.
class FramingRender strategy where Source #
The FramingRender class provides the logic for emitting a framing strategy.
The strategy transforms a SourceT m aSourceT m ByteString
Note: as the 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 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 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 -> IO a Source #
Instances
| MonadIO m => FromSourceIO a (SourceT m a) Source # | |
Defined in Servant.API.Stream | |
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
| 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 # | |
| 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 # | |
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
| 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 # | |
| 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 # | |
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
| 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 # | |
| 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 # | |
type StreamBody = StreamBody' '[] Source #
A stream request body.
data StreamBody' (mods :: [Type]) (framing :: Type) (contentType :: Type) (a :: Type) 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 Associated Types type Rep (StreamBody' mods framing contentType a) :: Type -> Type # Methods from :: StreamBody' mods framing contentType a -> Rep (StreamBody' mods framing contentType a) x # to :: Rep (StreamBody' mods framing contentType a) x -> StreamBody' mods framing contentType a # | |
| 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 StreamPost = Stream 'POST 200 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 (NonEmpty a) Source # | |
Defined in Servant.API.Stream Methods toSourceIO :: NonEmpty a -> SourceIO a Source # | |
| ToSourceIO a [a] Source # | |
Defined in Servant.API.Stream Methods toSourceIO :: [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 # | |
Authentication
data BasicAuth (realm :: Symbol) (userData :: Type) 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.
data BasicAuthData Source #
A simple datatype to hold data required to decorate a request
Constructors
| BasicAuthData | |
Fields | |
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
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 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 JSON Source # | application/json |
Defined in Servant.API.ContentTypes | |
| Accept OctetStream Source # | application/octet-stream |
Defined in Servant.API.ContentTypes Methods contentType :: Proxy OctetStream -> MediaType Source # contentTypes :: Proxy OctetStream -> NonEmpty MediaType Source # | |
| Accept PlainText Source # | text/plain;charset=utf-8 |
Defined in Servant.API.ContentTypes | |
data FormUrlEncoded Source #
Instances
Instances
| Accept JSON Source # | application/json |
Defined in Servant.API.ContentTypes | |
| ToJSON a => MimeRender JSON a Source # | |
Defined in Servant.API.ContentTypes Methods mimeRender :: Proxy JSON -> a -> ByteString Source # | |
| 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 # | |
| MimeRender JSON a => MimeRender JSON (WithStatus _status a) Source # | |
Defined in Servant.API.UVerb Methods mimeRender :: Proxy JSON -> WithStatus _status 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 # | |
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
A type for responses without content-body.
Constructors
| NoContent |
Instances
| Generic NoContent Source # | |
| Read NoContent Source # | |
| Show NoContent Source # | |
| NFData NoContent Source # | |
Defined in Servant.API.ContentTypes | |
| Eq NoContent Source # | |
| 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 | |
data OctetStream Source #
Instances
Instances
Serializing and deserializing types based on Accept and
Content-Type headers.
Response Headers
class AddHeader (mods :: [Type]) h v orig new | mods h v orig -> new, new -> mods, new -> h, new -> v, new -> orig Source #
Minimal complete definition
addOptionalHeader
Instances
| (KnownSymbol h, ToHttpApiData v, new ~ Headers '[Header' mods h v] a) => AddHeader mods h v a new Source # | |
Defined in Servant.API.ResponseHeaders Methods addOptionalHeader :: ResponseHeader h v -> a -> new | |
| (AddHeader mods h v old new, AddHeader mods h v (Union oldrest) (Union newrest), oldrest ~ (a ': as), newrest ~ (b ': bs)) => AddHeader mods h v (Union (old ': (a ': as))) (Union (new ': (b ': bs))) Source # | |
Defined in Servant.API.ResponseHeaders Methods addOptionalHeader :: ResponseHeader h v -> Union (old ': (a ': as)) -> Union (new ': (b ': bs)) | |
| AddHeader mods h v old new => AddHeader mods h v (Union '[old]) (Union '[new]) Source # | |
Defined in Servant.API.ResponseHeaders Methods addOptionalHeader :: ResponseHeader h v -> Union '[old] -> Union '[new] | |
| (KnownSymbol h, ToHttpApiData v) => AddHeader mods h v (Headers (fst ': rest) a) (Headers (Header' mods h v ': (fst ': rest)) a) Source # | |
Defined in Servant.API.ResponseHeaders Methods addOptionalHeader :: ResponseHeader h v -> Headers (fst ': rest) a -> Headers (Header' mods h v ': (fst ': rest)) a | |
class BuildHeadersTo hs where Source #
Methods
buildHeadersTo :: [Header] -> HList hs Source #
Instances
| BuildHeadersTo ('[] :: [Type]) Source # | |
Defined in Servant.API.ResponseHeaders Methods buildHeadersTo :: [Header] -> HList '[] Source # | |
| (FromHttpApiData v, BuildHeadersTo xs, KnownSymbol h) => BuildHeadersTo (Header' mods h v ': xs) Source # | |
Defined in Servant.API.ResponseHeaders | |
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 # | |
Constructors
| HNil :: HList '[] | |
| HCons :: ResponseHeader h x -> HList xs -> HList (Header' mods h x ': xs) |
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 # | |
class HasResponseHeader h a headers Source #
Minimal complete definition
hlistLookupHeader
Instances
| HasResponseHeader h a (Header' mods h a ': rest) Source # | |
Defined in Servant.API.ResponseHeaders Methods hlistLookupHeader :: HList (Header' mods h a ': rest) -> ResponseHeader h a | |
| HasResponseHeader h a rest => HasResponseHeader h a (first ': rest) Source # | |
Defined in Servant.API.ResponseHeaders Methods hlistLookupHeader :: HList (first ': rest) -> ResponseHeader h a | |
Response Header objects. You should never need to construct one directly.
Instead, use addOptionalHeader.
Constructors
| Headers | |
Fields
| |
Instances
| (KnownSymbol h, ToHttpApiData v) => AddHeader mods h v (Headers (fst ': rest) a) (Headers (Header' mods h v ': (fst ': rest)) a) Source # | |
Defined in Servant.API.ResponseHeaders Methods addOptionalHeader :: ResponseHeader h v -> Headers (fst ': rest) a -> Headers (Header' mods 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 # | |
| HasStatus a => HasStatus (Headers ls a) Source # | |
| type StatusOf (Headers ls a) Source # | |
Defined in Servant.API.UVerb | |
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 # (<$) :: a -> ResponseHeader sym b -> ResponseHeader sym a # | |
| Show a => Show (ResponseHeader sym a) Source # | |
Defined in Servant.API.ResponseHeaders Methods showsPrec :: Int -> ResponseHeader sym a -> ShowS # show :: ResponseHeader sym a -> String # showList :: [ResponseHeader sym a] -> ShowS # | |
| NFData a => NFData (ResponseHeader sym a) Source # | |
Defined in Servant.API.ResponseHeaders Methods rnf :: ResponseHeader sym a -> () # | |
| Eq a => Eq (ResponseHeader sym a) Source # | |
Defined in Servant.API.ResponseHeaders Methods (==) :: ResponseHeader sym a -> ResponseHeader sym a -> Bool # (/=) :: ResponseHeader sym a -> ResponseHeader sym a -> Bool # | |
addHeader :: AddHeader '[Optional, Strict] 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 example0 = addHeader 5 "hi" :: Headers '[Header "someheader" Int] String;>>>getHeaders example0[("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.
addHeader' :: AddHeader mods h v orig new => v -> orig -> new Source #
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
noHeader :: AddHeader '[Optional, Strict] 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[]
Untyped endpoints
Endpoint for plugging in your own Wai Applications.
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 Applications,
this can also be used with functions from
Servant.Server.StaticFiles
to serve static files stored in a particular directory on your filesystem
Variant of Raw that lets you access the underlying monadic context to process the request.
Plugging in a wai Application, serving directories
FromHttpApiData and ToHttpApiData
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
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 urlEncodeBuilder False
toHeader :: a -> ByteString Source #
Convert to HTTP header value.
toQueryParam :: a -> Text Source #
Convert to query param value.
toEncodedQueryParam :: a -> Builder Source #
Convert to URL query param,
The default definition uses urlEncodeBuilder True
Since: http-api-data-0.5.1
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
| 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 # gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c URI # dataTypeOf :: URI -> DataType # dataCast1 :: Typeable t => (forall d. Data d => c (t d)) -> Maybe (c URI) # dataCast2 :: Typeable t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c URI) # gmapT :: (forall b. Data b => b -> b) -> URI -> URI # gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> URI -> r # gmapQr :: forall r r'. (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> URI -> r # gmapQ :: (forall d. Data d => d -> u) -> URI -> [u] # gmapQi :: Int -> (forall d. Data d => d -> u) -> URI -> u # gmapM :: Monad m => (forall d. Data d => d -> m d) -> URI -> m URI # gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> URI -> m URI # gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> URI -> m URI # | |
| Generic URI | |
| Show URI | |
| NFData URI | |
Defined in Network.URI | |
| Eq URI | |
| Ord URI | |
| Lift URI | |
| type Rep URI | |
Defined in Network.URI type Rep URI = D1 ('MetaData "URI" "Network.URI" "network-uri-2.6.4.2-Dnf2sHP7gXHIY4t8lr2Jwz" '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))))) | |
class HasLink endpoint where Source #
Construct a toLink for an endpoint.
Methods
Instances
type family IsElem endpoint api :: Constraint where ... Source #
Closed type family, check if endpoint is within api.
Uses 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 (Header' mods 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 (NamedRoutes rs) = IsElem e (ToServantApi rs) | |
| 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
QueryParam
>>>data CustomThing>>>type instance IsElem' e (CustomThing :> s) = IsElem e s
Note that IsElemIsElem'
Once you have written a HasLink instance for CustomThing you are ready to go.
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 # toEncodedQueryParam :: Link -> Builder 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 ... #
Type-level If. If True a b ==> a; If False a b ==> b
data SBool (b :: Bool) where Source #
Instances
| EqP SBool | Since: singleton-bool-0.1.7 |
| GNFData SBool | Since: singleton-bool-0.1.6 |
Defined in Data.Singletons.Bool | |
| GCompare SBool | Since: singleton-bool-0.1.6 |
| GEq SBool |
Since: singleton-bool-0.1.6 |
| GRead SBool |
Since: singleton-bool-0.1.6 |
Defined in Data.Singletons.Bool | |
| GShow SBool |
Since: singleton-bool-0.1.6 |
Defined in Data.Singletons.Bool | |
| OrdP SBool | Since: singleton-bool-0.1.7 |
| Show (SBool b) | Since: singleton-bool-0.1.5 |
| SBoolI b => Boring (SBool b) | Since: singleton-bool-0.1.6 |
Defined in Data.Singletons.Bool | |
| NFData (SBool b) | Since: singleton-bool-0.1.6 |
Defined in Data.Singletons.Bool | |
| Eq (SBool b) | Since: singleton-bool-0.1.5 |
| Ord (SBool b) | Since: singleton-bool-0.1.5 |
Defined in Data.Singletons.Bool | |