WebApi.Server

Provides the implementation of web api. Given a contract, an implementation of the web api can be provided by using WebApiServer and ApiHandler. WebApiServer has the information pertaining to web api as a whole. ApiHandler provides a way to write the handler for a particular API end point.

Comparing with the WebApi.Contract, WebApi and ApiContract has the same relationship as WebApiServer and ApiHandler.

Creating a WAI application

serverApp :: (iface ~ ApiInterface server, Router server (Apis iface) `(CUSTOM "", `[]`)`) => ServerSettings -> server -> Application

Create a WAI application from the information specified in WebApiServer, WebApi, ApiContract and ApiHandler classes.

serverSettings :: ServerSettings

Default server settings.

data ServerSettings

Type of settings of the server.

Implementation of Api

class ApiContract (ApiInterface p) m r => ApiHandler p m r where

Describes the implementation of a single API end point corresponding to ApiContract (ApiInterface p) m r

Methods

handler :: (query ~ `[]`) => Tagged query p -> Request m r -> HandlerM p (Query (Response m r) query)

Handler for the API end point which returns a Response.

TODO : query type parameter is an experimental one used for trying out dependently typed params. This parameter will let us refine the ApiOut to the structure that is requested by the client. for eg : graph.facebook.com/bgolub?fields=id,name,picture

This feature is not finalized and might get changed / removed. Currently the return type of handler is equivalent to `Response m r`

Instances

(ApiContract p m r, Arbitrary (ApiOut m r), Arbitrary (ApiErr m r), Arbitrary (HeaderOut m r), Arbitrary (CookieOut m r), Typeable * m, Typeable * r) => ApiHandler (MockServer p) m r

data ApiException m r

Type of Exception raised in a handler.

Constructors

ApiException

Fields

apiException :: ApiError m r

Instances

Show (ApiException m r)

(Typeable * m, Typeable * r) => Exception (ApiException m r)

class (MonadCatch (HandlerM p), MonadIO (HandlerM p), WebApi (ApiInterface p)) => WebApiServer p where

Binds implementation to interface and provides a pluggable handler monad for the endpoint handler implementation.

Minimal complete definition

Nothing

Associated Types

type HandlerM p :: * -> *

Type of the handler Monad. It should implement MonadCatch and MonadIO classes. Defaults to IO.

type ApiInterface p :: *

Methods

toIO :: p -> HandlerM p a -> IO a

Create a value of IO a from HandlerM p a.

Instances

WebApi p => WebApiServer (MockServer p)

respond :: (Monad handM, HeaderOut m r ~ (), CookieOut m r ~ ()) => ApiOut m r -> handM (Response m r)

Creates a successful response from its components. It is assumed that HeaderOut and CookieOut has default definitions.

respondWith :: Monad handM => Status -> ApiOut m r -> HeaderOut m r -> CookieOut m r -> handM (Response m r)

Creates a successful response from its components.

raise :: (MonadThrow handM, Typeable m, Typeable r) => Status -> ApiErr m r -> handM (Response m r)

This function short circuits returning an ApiError.It is assumed that HeaderOut and CookieOut has default definitions.

raiseWith :: (MonadThrow handM, Typeable m, Typeable r) => Status -> ApiErr m r -> HeaderOut m r -> CookieOut m r -> handM (Response m r)

This function short circuits returning an ApiError.

Wrapping and unwrapping a Tagged

unTagged :: Tagged s b -> b

toTagged :: Proxy s -> b -> Tagged s b

Routing

module WebApi.Router

link :: (ToParam QueryParam (QueryParam m r), MkPathFormatString r, ToParam PathParam (PathParam m r)) => route m r -> URI -> PathParam m r -> Maybe (QueryParam m r) -> URI

Generate a type safe URL for a given route type. The URI can be used for setting a base URL if required.