APIBuilder.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 = EitherT (APIError e) (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

runAPI

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.

runRoute :: (FromJSON a, FromJSON 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.

routeResponse :: MonadIO m => 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

liftEither :: Monad m => EitherT (APIError e) (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.

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.