-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | Library for easily building REST API wrappers in Haskell -- -- Library for easily building REST API wrappers in Haskell @package api-builder @version 0.1.1.0 module APIBuilder.Query class ToQuery a toQuery :: ToQuery a => a -> Maybe 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 APIBuilder.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, Maybe 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, Maybe 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 APIBuilder.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) module APIBuilder.Decoding -- | Try to parse a value from a JSON ByteString, and if not, try -- to parse a useful error from the JSON. If we can't do that, complain -- about a ParseError. decode :: (FromJSON a, FromJSON e) => ByteString -> Either (APIError e) a module APIBuilder.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 APIBuilder.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) (StateT Builder (StateT s m)) a -- | Runs an API by executing its transformer stack and dumping it -- all into IO. runAPI :: MonadIO m => Builder -> s -> APIT s e m a -> m (Either (APIError 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. runRoute :: (FromJSON a, FromJSON e, MonadIO m) => Route -> APIT s e m a -- | Runs a Route, but only returns the response and does nothing -- towards decoding the response. routeResponse :: MonadIO m => 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) (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 () -- | Exports a bunch of stuff. Check API, Builder, -- Decoding, Error, and Routes. module APIBuilder -- | 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 APIBuilder.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 FromJSON Question