-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | Library for easily building REST API wrappers in Haskell
--
@package api-builder
@version 0.5.0.0
module Network.API.Builder.Query
class ToQuery a
toQuery :: ToQuery a => Text -> a -> [(Text, Text)]
instance ToQuery a => ToQuery [a]
instance ToQuery a => ToQuery (Maybe a)
instance ToQuery Text
instance ToQuery Int
instance ToQuery Bool
instance ToQuery Integer
module Network.API.Builder.Routes
-- | Main type for routes in the API. Used to represent the URL minus the
-- actual endpoint URL as well as the query string and the HTTP method
-- used to communicate with the server.
data Route
Route :: [URLFragment] -> [URLParam] -> Method -> Route
fragments :: Route -> [URLFragment]
urlParams :: Route -> [URLParam]
httpMethod :: Route -> Method
-- | Alias for Text to store the URL fragments for each
-- Route.
type URLFragment = Text
-- | Alias to (Text, Maybe Text) used to store each query that
-- gets tacked onto the request.
type URLParam = [(Text, Text)]
-- | Convenience function for building URLParams. Right-hand
-- argument must have a ToQuery instance so it can be converted
-- to the appropriate representation in a query string. Query values do
-- not need to be escaped.
--
--
-- >>> "api_type" =. ("json" :: Text)
-- ("api_type", Just "json")
--
(=.) :: ToQuery a => Text -> a -> [(Text, Text)]
-- | Converts a Route to a URL. Drops any Nothing values from the
-- query, separates the fragments with "/" and tacks them onto the end of
-- the base URL.
routeURL :: Text -> Route -> Text
instance Show Route
instance Read Route
instance Eq Route
module Network.API.Builder.Error
-- | Error type for the API, where a is the type that
-- should be returned when something goes wrong on the other end - i.e.
-- any error that isn't directly related to this library.
data APIError a
-- | A type that represents any error that happens on the API end. Define
-- your own custom type with a FromJSON instance if you want to
-- handle them, or you can use () if you just want to ignore
-- them all.
APIError :: a -> APIError a
-- | Something went wrong when we tried to do a HTTP operation.
HTTPError :: HttpException -> APIError a
-- | You're trying to create an invalid URL somewhere - check your
-- Builder's base URL and your Routes.
InvalidURLError :: APIError a
-- | Failed when parsing the response, and it wasn't an error on their end.
ParseError :: String -> APIError a
instance Show a => Show (APIError a)
instance Eq a => Eq (APIError a)
module Network.API.Builder.Receive
class Receivable r
receive :: (Receivable r, ErrorReceivable e) => Response ByteString -> Either (APIError e) r
useFromJSON :: (FromJSON a, ErrorReceivable e) => Response ByteString -> Either (APIError e) a
class ErrorReceivable e
receiveError :: ErrorReceivable e => Response ByteString -> Maybe e
useErrorFromJSON :: FromJSON a => Response ByteString -> Maybe a
eitherDecode :: FromJSON a => ByteString -> Either String a
newtype JSONResponse a
JSONResponse :: a -> JSONResponse a
unwrapJSON :: JSONResponse a -> a
instance Show a => Show (JSONResponse a)
instance Read a => Read (JSONResponse a)
instance Eq a => Eq (JSONResponse a)
instance Ord a => Ord (JSONResponse a)
instance FromJSON a => Receivable (JSONResponse a)
instance FromJSON a => FromJSON (JSONResponse a)
instance ErrorReceivable Value
instance ErrorReceivable ()
instance ErrorReceivable ByteString
instance Receivable Value
instance Receivable (Response ByteString)
instance Receivable ByteString
module Network.API.Builder.Builder
-- | Builder type for the API. Keeps track of the API's name and base URL,
-- and how to modify Routes and Requests before they're run.
data Builder
Builder :: Text -> Text -> (Route -> Route) -> (Request -> Request) -> Builder
_name :: Builder -> Text
_baseURL :: Builder -> Text
_customizeRoute :: Builder -> Route -> Route
_customizeRequest :: Builder -> Request -> Request
-- | Makes a basic builder, i.e. one that simply has a name and base URL
-- and doesn't fiddle with Routes / Requests.
basicBuilder :: Text -> Text -> Builder
instance Show Builder
module Network.API.Builder.Send
class Sendable s
send :: Sendable s => Builder -> Route -> s -> Maybe Request
instance Sendable ByteString
instance Sendable Value
instance Sendable ()
module Network.API.Builder.API
-- | 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 API s e a = APIT s e IO 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.
type APIT s e m a = EitherT (APIError e) (ReaderT Manager (StateT Builder (StateT s m))) a
-- | Runs an API by executing its transformer stack and dumping it
-- all into IO. Only returns the actual result.
execAPI :: MonadIO m => Builder -> s -> APIT s e m a -> m (Either (APIError e) a)
-- | 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.
runAPI :: MonadIO m => Builder -> Manager -> s -> APIT s e m a -> m (Either (APIError e) a, Builder, s)
-- | Runs a Route. Infers the type to convert to from the JSON
-- with the a in API, and infers the error type from
-- e.
runRoute :: (Receivable a, ErrorReceivable e, MonadIO m) => Route -> APIT s e m a
sendRoute :: (MonadIO m, Sendable t, ErrorReceivable e, Receivable r) => t -> Route -> APIT s e m r
-- | Runs a Route, but only returns the response and does nothing
-- towards decoding the response.
routeResponse :: (MonadIO m, ErrorReceivable e) => Route -> APIT s e m (Response ByteString)
-- | 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.
routeRequest :: Builder -> Route -> Maybe Request
-- | 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 => EitherT (APIError e) (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.
liftManager :: Monad m => ReaderT Manager (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.
liftBuilder :: Monad m => StateT Builder (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.
liftState :: Monad m => StateT s m a -> APIT s e m a
-- | 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.
name :: 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.
baseURL :: Monad m => Text -> APIT s e m ()
-- | Modify every Route before it runs. Useful for adding extra
-- params to every query, for example.
customizeRoute :: Monad m => (Route -> Route) -> APIT s e m ()
-- | Modify every Request before the API fetches it. Useful for
-- adding headers to every request, for example.
customizeRequest :: Monad m => (Request -> Request) -> APIT s e m ()
-- | Entirely re-exports.
module Network.API.Builder
-- | Defines a basic example of API use - check the readme for more detail
-- or check the tutorial at
-- https://github.com/intolerable/api-builder
module Network.API.Builder.Examples.StackOverflow
data Question
Question :: Text -> Bool -> Int -> [Text] -> Question
title :: Question -> Text
isAnswered :: Question -> Bool
score :: Question -> Int
tags :: Question -> [Text]
newtype Questions
Questions :: [Question] -> Questions
stackOverflow :: Builder
answersRoute :: Route
getAnswers :: IO (Either (APIError ()) Questions)
instance Show Question
instance Eq Question
instance Show Questions
instance Eq Questions
instance FromJSON Questions
instance Receivable Questions
instance FromJSON Question