-- 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.0.1 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] -> HTTPMethod -> Route fragments :: Route -> [URLFragment] urlParams :: Route -> [URLParam] httpMethod :: Route -> HTTPMethod -- | 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. -- -- 
--   >>> "api_type" =. Just "json"
--   ("api_type", Just "json")
--
(=.) :: Text -> Maybe Text -> (Text, Maybe Text) -- | Type for different HTTP request methods. Has the two most common ones -- (GET and POST) as well as support for custom methods. data HTTPMethod GET :: HTTPMethod POST :: HTTPMethod CustomMethod :: Text -> HTTPMethod -- | Get a String from a HTTPMethod. Used mostly for creating -- Requests. -- -- 
--   >>> showMethod GET
--   "GET"
--   
--   >>> showMethod (CustomMethod "PATCH")
--   "PATCH"
--
showMethod :: HTTPMethod -> String -- | 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 HTTPMethod instance Read HTTPMethod instance Eq HTTPMethod 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. type API s e a = EitherT (APIError e) (StateT Builder (StateT s IO)) a -- | Runs an API by executing its transformer stack and dumping it -- all into IO. runAPI :: Builder -> s -> API s e a -> IO (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) => Route -> API s e a -- | 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 :: EitherT (APIError e) (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. liftBuilder :: StateT Builder (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. liftState :: StateT s IO a -> API s e 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 :: 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. baseURL :: Text -> API s e () -- | Modify every Route before it runs. Useful for adding extra -- params to every query, for example. customizeRoute :: (Route -> Route) -> API s e () -- | Modify every Request before the API fetches it. Useful for -- adding headers to every request, for example. customizeRequest :: (Request -> Request) -> API s e () -- | 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