api-builder-0.11.0.0: Library for easily building REST API wrappers in Haskell

Safe HaskellNone
LanguageHaskell2010

Network.API.Builder.API

Contents

Synopsis

API

type API s e a = APIT s e IO a Source

Main API type. s is the API's internal state, e is the API's custom error type, and a is the result when the API runs. Based on the APIT transformer.

type APIT s e m a = ExceptT (APIError e) (ReaderT Manager (StateT Builder (StateT s m))) a Source

Main API transformer type. s is the API's internal state, e is the API's custom error type, and a is the result when the API runs.

Running the API

execAPI Source

Arguments

:: MonadIO m 
=> Builder

initial Builder for the API

-> s

initial state s for the API

-> APIT s e m a

the actual API to run

-> m (Either (APIError e) a)

IO action that returns either an error or the result

Runs an API by executing its transformer stack and dumping it all into IO. Only returns the actual result.

runAPI Source

Arguments

:: MonadIO m 
=> Builder

initial Builder for the API

-> Manager

manager for working with conduit functions

-> s

initial state s for the API

-> APIT s e m a

the actual API to run

-> m (Either (APIError e) a, Builder, s)

IO action that returns either an error or the result, as well as the final states

Runs an API by executing its transformer stack and dumping it all into IO. | Returns the actual result as well as the final states of the Builder and custom state s.

runRoute :: (Receivable a, ErrorReceivable e, MonadIO m) => Route -> APIT s e m a Source

Runs a Route. Infers the type to convert to from the JSON with the a in API, and infers the error type from e.

routeResponse :: (MonadIO m, ErrorReceivable e) => Route -> APIT s e m (Response ByteString) Source

Runs a Route, but only returns the response and does nothing towards decoding the response.

routeRequest :: Builder -> Route -> Maybe Request Source

Try to construct a Request from a Route (with the help of the Builder). Returns Nothing if the URL is invalid or there is another error with the Route.

Lifting

liftExcept :: Monad m => ExceptT (APIError e) (ReaderT Manager (StateT Builder (StateT s m))) a -> APIT s e m a Source

Lifts an action that works on an API to an action that works on an API. This function is provided solely for future-proofing in the case that more transformers need to be stacked on top - it's implemented simply as id for the moment.

liftEither :: Monad m => ExceptT (APIError e) (ReaderT Manager (StateT Builder (StateT s m))) a -> APIT s e m a Source

Deprecated: Use liftExcept

Identical to liftExcept, provided for (almost) compatibility.

liftManager :: Monad m => ReaderT Manager (StateT Builder (StateT s m)) a -> APIT s e m a Source

Lifts an action that works on a Manager to one that works on an API.

liftBuilder :: Monad m => StateT Builder (StateT s m) a -> APIT s e m a Source

Lifts an action that operates on a Builder to one that works on an API. Useful mainly for gaining access to a Builder from inside an API.

liftState :: Monad m => StateT s m a -> APIT s e m a Source

Lifts an action on an API's state type s to one that works on the API. Good for messing with the state from inside the API.

Changing the Builder within the API

name :: Monad m => Text -> APIT s e m () Source

Modify the name of the Builder from inside an API. Using this is probably not the best idea, it's nice if the Builder's name is stable at least.

baseURL :: Monad m => Text -> APIT s e m () Source

Modify the baseURL of the Builder from inside an API. Can be useful for changing the API's endpoints for certain requests.

customizeRoute :: Monad m => (Route -> Route) -> APIT s e m () Source

Modify every Route before it runs. Useful for adding extra params to every query, for example.

customizeRequest :: Monad m => (Request -> Request) -> APIT s e m () Source

Modify every Request before the API fetches it. Useful for adding headers to every request, for example.