goggles 0.3.1 → 0.3.2

raw patch · 3 files changed

+36/−24 lines, 3 filesPVP: major bump suggested

API removals or changes: PVP suggests a major version bump

API changes (from Hackage documentation)

Files

• goggles.cabal +1/−1
• src/Network/Goggles.hs +8/−8
• src/Network/Utils/HTTP.hs +27/−15

@@ -1,5 +1,5 @@ name:                goggles-version:             0.3.1+version:             0.3.2 synopsis:            Extensible interface to Web APIs description:         `goggles` helps with exchanging data with APIs that require authentication. In particular, it handles the details of expiring session tokens, so the user does not have to implement this logic in her program. homepage:            https://github.com/ocramz/goggles

@@ -7,7 +7,7 @@ Stability   : experimental Portability : POSIX -== Introduction+= Introduction  This library aims to abstract away (part of) the bookkeeping related to exchanging data with web APIs. @@ -17,7 +17,7 @@   -== Preliminaries+= Preliminaries  @ import Network.Goggles@@ -25,7 +25,7 @@  Required language extensions: `OverloadedStrings`, `TypeFamilies`, `FlexibleInstances` . -== Usage+= Usage  To begin with, the user provides a type for the remote service she wishes to interface to, along with a couple typeclass instances. @@ -64,7 +64,7 @@  Once this is in place, a valid token can always be retrieved with 'accessToken'. This checks the validity of the locally cached token and performs a 'tokenFetch' only when this is about to expire. -=== Exception handling+= Exception handling  Internally, `goggles` uses `req` for HTTP connections, so the user must always provide a 'MonadHttp' instance for her 'Remote' type : @@ -75,13 +75,13 @@  The actual implementation of `handleHttpException` depends on the actual API semantics, but the user can just use 'throwM' here (imported from the 'Control.Monad.Catch' module of the `exceptions` package). -=== Putting it all together+= Putting it all together  The usual workflow is as follows: -* Create a 'Handle' with 'createHandle'. This requires a surrounding IO block because token refreshing is done as an atomic update in the STM monad.+* Create a 'Handle' from the API credentials and any API options with 'createHandle'. This requires a surrounding IO block because token refreshing is done as an atomic update in the STM monad. -* Compose the program that interacts with the external API in the 'WebApiM' monad.+* Build up the program that interacts with the external API in the 'WebApiM' monad.  * Run the program using the handle with 'evalWebApiIO'. @@ -91,7 +91,7 @@   -- * Sending and receiving data   getLbs, postLbs, putLbs,   -- * Sending and receiving data, with token authentication-  getLbsWithToken, sendWithToken, +  getLbsWithToken, postLbsWithToken, putLbsWithToken,    -- * Running WebApiM programs     createHandle       , evalWebApiIO

@@ -11,29 +11,41 @@  -- | Create an authenticated 'GET' call getLbsWithToken :: (HasCredentials c, HasToken c, MonadHttp (WebApiM c)) =>-                   (TokenContent c -> Url scheme -> Option scheme -> (Url scheme, Option scheme))-                -> Url scheme-                -> Option scheme+                   (TokenContent c -> Url scheme -> Option scheme -> (Url scheme, Option scheme)) -- ^ Modify request URL and/or request 'Option's using the token data+                -> Url scheme    -- ^ Initial URL+                -> Option scheme -- ^ Initial 'Option's                 -> WebApiM c LbsResponse getLbsWithToken fOpts uri opts = do   tok <- accessToken   let (uri', opts') = fOpts tok uri opts   getLbs uri' opts' --- | Sending data with an authenticated call------ The first function argument may be either 'postLbs' or 'putLbs'-sendWithToken :: HasToken c =>-                 (Url scheme -> Option scheme -> LB.ByteString -> WebApiM c b)-              -> (TokenContent c -> Url scheme -> Option scheme -> LB.ByteString -> (Url scheme, Option scheme, LB.ByteString))-              -> Url scheme-              -> Option scheme-              -> LB.ByteString-              -> WebApiM c b-sendWithToken f fOpts uri opts body = do   ++-- | Create an authenticated 'POST' call+postLbsWithToken :: (HasCredentials c, HasToken c, MonadHttp (WebApiM c)) =>+                   (TokenContent c -> Url scheme -> Option scheme -> LB.ByteString ->  (Url scheme, Option scheme, LB.ByteString)) -- ^ Modify request URL, request 'Option's and/or request body using the token data++                -> Url scheme     -- ^ Initial URL+                -> Option scheme  -- ^ Initial 'Option's+                -> LB.ByteString  -- ^ Initial request body+                -> WebApiM c LbsResponse+postLbsWithToken  fOpts uri opts body = do      tok <- accessToken   let (uri', opts', body') = fOpts tok uri opts body-  f uri' opts' body'+  postLbs uri' opts' body'++-- | Create an authenticated 'PUT' call+putLbsWithToken :: (HasCredentials c, HasToken c, MonadHttp (WebApiM c)) =>+                   (TokenContent c -> Url scheme -> Option scheme -> LB.ByteString ->  (Url scheme, Option scheme, LB.ByteString))   -- ^ Modify request URL, request 'Option's and/or request body using the token data++                -> Url scheme  -- ^ Initial URL+                -> Option scheme -- ^ Initial 'Option's+                -> LB.ByteString -- ^ Initial request body+                -> WebApiM c LbsResponse+putLbsWithToken  fOpts uri opts body = do   +  tok <- accessToken+  let (uri', opts', body') = fOpts tok uri opts body+  putLbs uri' opts' body'    -- | 'GET' a lazy bytestring from an API endpoint getLbs :: (HasCredentials c, MonadHttp (WebApiM c)) =>