Maintainer	Brandon Chinn <brandon@leapyear.io>
Stability	experimental
Portability	portable
Safe Haskell	None
Language	Haskell2010

GitHub.REST

Contents

Monad transformer and type-class for querying the GitHub REST API
GitHub authentication
GitHub Endpoints
KeyValue pairs
Helpers
Re-exports

Description

Definitions for querying the GitHub REST API. See README.md for an example.

Synopsis

class Monad m => MonadGitHubREST m where
- queryGitHubPage' :: FromJSON a => GHEndpoint -> m (Either (Text, Text) (a, PageLinks))
- queryGitHubPage :: FromJSON a => GHEndpoint -> m (a, PageLinks)
- queryGitHub :: FromJSON a => GHEndpoint -> m a
- queryGitHubAll :: (FromJSON a, Monoid a) => GHEndpoint -> m a
- queryGitHub_ :: GHEndpoint -> m ()
data GitHubT m a
data GitHubState = GitHubState {
- token :: Maybe Token
- userAgent :: ByteString
- apiVersion :: ByteString
}
runGitHubT :: MonadIO m => GitHubState -> GitHubT m a -> m a
data Token
- = AccessToken ByteString
- | BearerToken ByteString
data GHEndpoint = GHEndpoint {
- method :: StdMethod
- endpoint :: Text
- endpointVals :: EndpointVals
- ghData :: GitHubData
}
type GitHubData = [KeyValue]
type EndpointVals = [KeyValue]
data KeyValue where
- (:=) :: (Show v, ToJSON v) => Text -> v -> KeyValue
githubTry :: MonadUnliftIO m => m a -> m (Either Value a)
githubTry' :: MonadUnliftIO m => Status -> m a -> m (Either Value a)
(.:) :: FromJSON a => Value -> Text -> a
data StdMethod
- = GET
- | POST
- | HEAD
- | PUT
- | DELETE
- | TRACE
- | CONNECT
- | OPTIONS
- | PATCH

Monad transformer and type-class for querying the GitHub REST API

class Monad m => MonadGitHubREST m where Source #

A type class for monads that can query the GitHub REST API.

Example:

-- create the "foo" branch
queryGitHub GHEndpoint
  { method = POST
  , endpoint = "/repos/:owner/:repo/git/refs"
  , endpointVals =
    [ "owner" := "alice"
    , "repo" := "my-project"
    ]
  , ghData =
    [ "ref" := "refs/heads/foo"
    , "sha" := "1234567890abcdef"
    ]
  }

It's recommended that you create functions for the API endpoints you're using:

deleteBranch branch = queryGitHub GHEndpoint
  { method = DELETE
  , endpoint = "/repos/:owner/:repo/git/refs/:ref"
  , endpointVals =
    [ "owner" := "alice"
    , "repo" := "my-project"
    , "ref" := "heads/" <> branch
    ]
  , ghData = []
  }

Minimal complete definition

queryGitHubPage'

Methods

queryGitHubPage' :: FromJSON a => GHEndpoint -> m (Either (Text, Text) (a, PageLinks)) Source #

Query GitHub, returning Right (payload, links) if successful, where payload is the response that GitHub sent back and links containing any pagination links GitHub may have sent back. If the response could not be decoded as JSON, returns Left (error message, response from server).

Errors on network connection failures or if GitHub sent back an error message. Use githubTry if you wish to handle GitHub errors.

queryGitHubPage :: FromJSON a => GHEndpoint -> m (a, PageLinks) Source #

queryGitHubPage', except calls fail if JSON decoding fails.

queryGitHub :: FromJSON a => GHEndpoint -> m a Source #

queryGitHubPage, except ignoring pagination links.

queryGitHubAll :: (FromJSON a, Monoid a) => GHEndpoint -> m a Source #

Repeatedly calls queryGitHubPage for each page returned by GitHub and concatenates the results.

queryGitHub_ :: GHEndpoint -> m () Source #

queryGitHub, except ignores the result.

Instances

MonadGitHubREST m => MonadGitHubREST (MaybeT m) Source #
Instance details Defined in GitHub.REST.Monad.Class Methods queryGitHubPage' :: FromJSON a => GHEndpoint -> MaybeT m (Either (Text, Text) (a, PageLinks)) Source # queryGitHubPage :: FromJSON a => GHEndpoint -> MaybeT m (a, PageLinks) Source # queryGitHub :: FromJSON a => GHEndpoint -> MaybeT m a Source # queryGitHubAll :: (FromJSON a, Monoid a) => GHEndpoint -> MaybeT m a Source # queryGitHub_ :: GHEndpoint -> MaybeT m () Source #
MonadIO m => MonadGitHubREST (GitHubT m) Source #
Instance details Defined in GitHub.REST.Monad Methods queryGitHubPage' :: FromJSON a => GHEndpoint -> GitHubT m (Either (Text, Text) (a, PageLinks)) Source # queryGitHubPage :: FromJSON a => GHEndpoint -> GitHubT m (a, PageLinks) Source # queryGitHub :: FromJSON a => GHEndpoint -> GitHubT m a Source # queryGitHubAll :: (FromJSON a, Monoid a) => GHEndpoint -> GitHubT m a Source # queryGitHub_ :: GHEndpoint -> GitHubT m () Source #
MonadGitHubREST m => MonadGitHubREST (ExceptT e m) Source #
Instance details Defined in GitHub.REST.Monad.Class Methods queryGitHubPage' :: FromJSON a => GHEndpoint -> ExceptT e m (Either (Text, Text) (a, PageLinks)) Source # queryGitHubPage :: FromJSON a => GHEndpoint -> ExceptT e m (a, PageLinks) Source # queryGitHub :: FromJSON a => GHEndpoint -> ExceptT e m a Source # queryGitHubAll :: (FromJSON a, Monoid a) => GHEndpoint -> ExceptT e m a Source # queryGitHub_ :: GHEndpoint -> ExceptT e m () Source #
MonadGitHubREST m => MonadGitHubREST (IdentityT m) Source #
Instance details Defined in GitHub.REST.Monad.Class Methods queryGitHubPage' :: FromJSON a => GHEndpoint -> IdentityT m (Either (Text, Text) (a, PageLinks)) Source # queryGitHubPage :: FromJSON a => GHEndpoint -> IdentityT m (a, PageLinks) Source # queryGitHub :: FromJSON a => GHEndpoint -> IdentityT m a Source # queryGitHubAll :: (FromJSON a, Monoid a) => GHEndpoint -> IdentityT m a Source # queryGitHub_ :: GHEndpoint -> IdentityT m () Source #
MonadGitHubREST m => MonadGitHubREST (StateT s m) Source #
Instance details Defined in GitHub.REST.Monad.Class Methods queryGitHubPage' :: FromJSON a => GHEndpoint -> StateT s m (Either (Text, Text) (a, PageLinks)) Source # queryGitHubPage :: FromJSON a => GHEndpoint -> StateT s m (a, PageLinks) Source # queryGitHub :: FromJSON a => GHEndpoint -> StateT s m a Source # queryGitHubAll :: (FromJSON a, Monoid a) => GHEndpoint -> StateT s m a Source # queryGitHub_ :: GHEndpoint -> StateT s m () Source #
MonadGitHubREST m => MonadGitHubREST (StateT s m) Source #
Instance details Defined in GitHub.REST.Monad.Class Methods queryGitHubPage' :: FromJSON a => GHEndpoint -> StateT s m (Either (Text, Text) (a, PageLinks)) Source # queryGitHubPage :: FromJSON a => GHEndpoint -> StateT s m (a, PageLinks) Source # queryGitHub :: FromJSON a => GHEndpoint -> StateT s m a Source # queryGitHubAll :: (FromJSON a, Monoid a) => GHEndpoint -> StateT s m a Source # queryGitHub_ :: GHEndpoint -> StateT s m () Source #
(Monoid w, MonadGitHubREST m) => MonadGitHubREST (WriterT w m) Source #
Instance details Defined in GitHub.REST.Monad.Class Methods queryGitHubPage' :: FromJSON a => GHEndpoint -> WriterT w m (Either (Text, Text) (a, PageLinks)) Source # queryGitHubPage :: FromJSON a => GHEndpoint -> WriterT w m (a, PageLinks) Source # queryGitHub :: FromJSON a => GHEndpoint -> WriterT w m a Source # queryGitHubAll :: (FromJSON a, Monoid a) => GHEndpoint -> WriterT w m a Source # queryGitHub_ :: GHEndpoint -> WriterT w m () Source #
(Monoid w, MonadGitHubREST m) => MonadGitHubREST (WriterT w m) Source #
Instance details Defined in GitHub.REST.Monad.Class Methods queryGitHubPage' :: FromJSON a => GHEndpoint -> WriterT w m (Either (Text, Text) (a, PageLinks)) Source # queryGitHubPage :: FromJSON a => GHEndpoint -> WriterT w m (a, PageLinks) Source # queryGitHub :: FromJSON a => GHEndpoint -> WriterT w m a Source # queryGitHubAll :: (FromJSON a, Monoid a) => GHEndpoint -> WriterT w m a Source # queryGitHub_ :: GHEndpoint -> WriterT w m () Source #
MonadGitHubREST m => MonadGitHubREST (ReaderT r m) Source #
Instance details Defined in GitHub.REST.Monad.Class Methods queryGitHubPage' :: FromJSON a => GHEndpoint -> ReaderT r m (Either (Text, Text) (a, PageLinks)) Source # queryGitHubPage :: FromJSON a => GHEndpoint -> ReaderT r m (a, PageLinks) Source # queryGitHub :: FromJSON a => GHEndpoint -> ReaderT r m a Source # queryGitHubAll :: (FromJSON a, Monoid a) => GHEndpoint -> ReaderT r m a Source # queryGitHub_ :: GHEndpoint -> ReaderT r m () Source #
(Monoid w, MonadGitHubREST m) => MonadGitHubREST (RWST r w s m) Source #
Instance details Defined in GitHub.REST.Monad.Class Methods queryGitHubPage' :: FromJSON a => GHEndpoint -> RWST r w s m (Either (Text, Text) (a, PageLinks)) Source # queryGitHubPage :: FromJSON a => GHEndpoint -> RWST r w s m (a, PageLinks) Source # queryGitHub :: FromJSON a => GHEndpoint -> RWST r w s m a Source # queryGitHubAll :: (FromJSON a, Monoid a) => GHEndpoint -> RWST r w s m a Source # queryGitHub_ :: GHEndpoint -> RWST r w s m () Source #
(Monoid w, MonadGitHubREST m) => MonadGitHubREST (RWST r w s m) Source #
Instance details Defined in GitHub.REST.Monad.Class Methods queryGitHubPage' :: FromJSON a => GHEndpoint -> RWST r w s m (Either (Text, Text) (a, PageLinks)) Source # queryGitHubPage :: FromJSON a => GHEndpoint -> RWST r w s m (a, PageLinks) Source # queryGitHub :: FromJSON a => GHEndpoint -> RWST r w s m a Source # queryGitHubAll :: (FromJSON a, Monoid a) => GHEndpoint -> RWST r w s m a Source # queryGitHub_ :: GHEndpoint -> RWST r w s m () Source #

data GitHubT m a Source #

A simple monad that can run REST calls.

Instances

MonadTrans GitHubT Source #
Instance details Defined in GitHub.REST.Monad Methods lift :: Monad m => m a -> GitHubT m a #
Monad m => Monad (GitHubT m) Source #
Instance details Defined in GitHub.REST.Monad Methods (>>=) :: GitHubT m a -> (a -> GitHubT m b) -> GitHubT m b # (>>) :: GitHubT m a -> GitHubT m b -> GitHubT m b # return :: a -> GitHubT m a # fail :: String -> GitHubT m a #
Functor m => Functor (GitHubT m) Source #
Instance details Defined in GitHub.REST.Monad Methods fmap :: (a -> b) -> GitHubT m a -> GitHubT m b # (<$) :: a -> GitHubT m b -> GitHubT m a #
MonadFail m => MonadFail (GitHubT m) Source #
Instance details Defined in GitHub.REST.Monad Methods fail :: String -> GitHubT m a #
Applicative m => Applicative (GitHubT m) Source #
Instance details Defined in GitHub.REST.Monad Methods pure :: a -> GitHubT m a # (<>) :: GitHubT m (a -> b) -> GitHubT m a -> GitHubT m b # liftA2 :: (a -> b -> c) -> GitHubT m a -> GitHubT m b -> GitHubT m c # (>) :: GitHubT m a -> GitHubT m b -> GitHubT m b # (<*) :: GitHubT m a -> GitHubT m b -> GitHubT m a #
MonadIO m => MonadIO (GitHubT m) Source #
Instance details Defined in GitHub.REST.Monad Methods liftIO :: IO a -> GitHubT m a #
MonadUnliftIO m => MonadUnliftIO (GitHubT m) Source #
Instance details Defined in GitHub.REST.Monad Methods withRunInIO :: ((forall a. GitHubT m a -> IO a) -> IO b) -> GitHubT m b #
MonadIO m => MonadGitHubREST (GitHubT m) Source #
Instance details Defined in GitHub.REST.Monad Methods queryGitHubPage' :: FromJSON a => GHEndpoint -> GitHubT m (Either (Text, Text) (a, PageLinks)) Source # queryGitHubPage :: FromJSON a => GHEndpoint -> GitHubT m (a, PageLinks) Source # queryGitHub :: FromJSON a => GHEndpoint -> GitHubT m a Source # queryGitHubAll :: (FromJSON a, Monoid a) => GHEndpoint -> GitHubT m a Source # queryGitHub_ :: GHEndpoint -> GitHubT m () Source #

data GitHubState Source #

Constructors

GitHubState

Fields

token :: Maybe Token
The token to use to authenticate with the API.
userAgent :: ByteString
The user agent to use when interacting with the API: https://developer.github.com/v3/#user-agent-required
apiVersion :: ByteString
The media type will be sent as: application/vnd.github.VERSION+json. For the standard API endpoints, "v3" should be sufficient here. See https://developer.github.com/v3/media/

runGitHubT :: MonadIO m => GitHubState -> GitHubT m a -> m a Source #

Run the given GitHubT action with the given token and user agent.

The token will be sent with each API request -- see Token. The user agent is also required for each API request -- see https://developer.github.com/v3/#user-agent-required.

GitHub authentication

data Token Source #

The token to use to authenticate with GitHub.

Constructors

AccessToken ByteString	https://developer.github.com/v3/#authentication
BearerToken ByteString	https://developer.github.com/apps/building-github-apps/authenticating-with-github-apps/#authenticating-as-a-github-app

Instances

Show Token Source #
Instance details Defined in GitHub.REST.Auth Methods showsPrec :: Int -> Token -> ShowS # show :: Token -> String # showList :: [Token] -> ShowS #

GitHub Endpoints

data GHEndpoint Source #

A call to a GitHub API endpoint.

Constructors

GHEndpoint

Fields

method :: StdMethod
endpoint :: Text
The GitHub API endpoint, with colon-prefixed components that will be replaced; e.g. "/users/:username/repos"
endpointVals :: EndpointVals
Key-value pairs to replace colon-prefixed components in endpoint; e.g. [ "username" := ("alice" :: Text) ]
ghData :: GitHubData
Key-value pairs to send in the request body; e.g. [ "sort" := ("created" :: Text), "direction" := ("asc" :: Text) ]

type GitHubData = [KeyValue] Source #

type EndpointVals = [KeyValue] Source #

KeyValue pairs

data KeyValue where Source #

A type representing a key-value pair.

Constructors

(:=) :: (Show v, ToJSON v) => Text -> v -> KeyValue infixr 1

Instances

Show KeyValue Source #
Instance details Defined in GitHub.REST.KeyValue Methods showsPrec :: Int -> KeyValue -> ShowS # show :: KeyValue -> String # showList :: [KeyValue] -> ShowS #
ToJSON [KeyValue] Source #
Instance details Defined in GitHub.REST.KeyValue Methods toJSON :: [KeyValue] -> Value # toEncoding :: [KeyValue] -> Encoding # toJSONList :: [[KeyValue]] -> Value # toEncodingList :: [[KeyValue]] -> Encoding #

Helpers

githubTry :: MonadUnliftIO m => m a -> m (Either Value a) Source #

Handle 422 exceptions thrown by the GitHub REST API.

Most client errors are 422, since we should always be sending valid JSON. If an endpoint throws different error codes, use githubTry'.

https://developer.github.com/v3/#client-errors

githubTry' :: MonadUnliftIO m => Status -> m a -> m (Either Value a) Source #

Handle the given exception thrown by the GitHub REST API.

(.:) :: FromJSON a => Value -> Text -> a Source #

Get the given key from the Value, erroring if it doesn't exist.

Re-exports

data StdMethod #

HTTP standard method (as defined by RFC 2616, and PATCH which is defined by RFC 5789).

Constructors

GET
POST
HEAD
PUT
DELETE
TRACE
CONNECT
OPTIONS
PATCH

Instances

Bounded StdMethod
Instance details Defined in Network.HTTP.Types.Method Methods minBound :: StdMethod # maxBound :: StdMethod #
Enum StdMethod
Instance details Defined in Network.HTTP.Types.Method Methods succ :: StdMethod -> StdMethod # pred :: StdMethod -> StdMethod # toEnum :: Int -> StdMethod # fromEnum :: StdMethod -> Int # enumFrom :: StdMethod -> [StdMethod] # enumFromThen :: StdMethod -> StdMethod -> [StdMethod] # enumFromTo :: StdMethod -> StdMethod -> [StdMethod] # enumFromThenTo :: StdMethod -> StdMethod -> StdMethod -> [StdMethod] #
Eq StdMethod
Instance details Defined in Network.HTTP.Types.Method Methods (==) :: StdMethod -> StdMethod -> Bool # (/=) :: StdMethod -> StdMethod -> Bool #
Ord StdMethod
Instance details Defined in Network.HTTP.Types.Method Methods compare :: StdMethod -> StdMethod -> Ordering # (<) :: StdMethod -> StdMethod -> Bool # (<=) :: StdMethod -> StdMethod -> Bool # (>) :: StdMethod -> StdMethod -> Bool # (>=) :: StdMethod -> StdMethod -> Bool # max :: StdMethod -> StdMethod -> StdMethod # min :: StdMethod -> StdMethod -> StdMethod #
Read StdMethod
Instance details Defined in Network.HTTP.Types.Method Methods readsPrec :: Int -> ReadS StdMethod # readList :: ReadS [StdMethod] # readPrec :: ReadPrec StdMethod # readListPrec :: ReadPrec [StdMethod] #
Show StdMethod
Instance details Defined in Network.HTTP.Types.Method Methods showsPrec :: Int -> StdMethod -> ShowS # show :: StdMethod -> String # showList :: [StdMethod] -> ShowS #
Ix StdMethod
Instance details Defined in Network.HTTP.Types.Method Methods range :: (StdMethod, StdMethod) -> [StdMethod] # index :: (StdMethod, StdMethod) -> StdMethod -> Int # unsafeIndex :: (StdMethod, StdMethod) -> StdMethod -> Int inRange :: (StdMethod, StdMethod) -> StdMethod -> Bool # rangeSize :: (StdMethod, StdMethod) -> Int # unsafeRangeSize :: (StdMethod, StdMethod) -> Int