Network.API.Builder.API

API

type API s e a = APIT s e IO a

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

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

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

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

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

sendRoute :: (MonadIO m, Sendable t, ErrorReceivable e, Receivable r) => t -> Route -> APIT s e m r

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

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

routeRequest :: Builder -> Route -> Maybe Request

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

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

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

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

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

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 ()

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 ()

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 ()

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 ()

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