APIBuilder.API

API

type API s e a = EitherT (APIError e) (StateT Builder (StateT s 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.

Running the API

runAPI

Arguments

:: Builder

initial Builder for the API

-> s

initial state s for the API

-> API s e a

the actual API to run

-> IO (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) => Route -> API s e 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.

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 :: EitherT (APIError e) (StateT Builder (StateT s IO)) a -> API s e 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 :: StateT Builder (StateT s IO) a -> API s e 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 :: StateT s IO a -> API s e 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 :: Text -> API s e ()

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 :: Text -> API s e ()

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

customizeRoute :: (Route -> Route) -> API s e ()

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

customizeRequest :: (Request -> Request) -> API s e ()

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