Maintainer | Brandon Chinn <brandon@leapyear.io> |
---|---|
Stability | experimental |
Portability | portable |
Safe Haskell | None |
Language | Haskell2010 |
GitHub.REST
Contents
Description
Definitions for querying the GitHub REST API. See README.md for an example.
Synopsis
- class MonadFail 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 {}
- runGitHubT :: MonadIO m => GitHubState -> GitHubT m a -> m a
- data Token
- data GHEndpoint = GHEndpoint {}
- type GitHubData = [KeyValue]
- type EndpointVals = [KeyValue]
- data KeyValue where
- 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
Monad transformer and type-class for querying the GitHub REST API
class MonadFail 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
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
A simple monad that can run REST calls.
Instances
MonadTrans GitHubT Source # | |
Defined in GitHub.REST.Monad | |
Monad m => Monad (GitHubT m) Source # | |
Functor m => Functor (GitHubT m) Source # | |
MonadFail m => MonadFail (GitHubT m) Source # | |
Defined in GitHub.REST.Monad | |
Applicative m => Applicative (GitHubT m) Source # | |
MonadIO m => MonadIO (GitHubT m) Source # | |
Defined in GitHub.REST.Monad | |
MonadUnliftIO m => MonadUnliftIO (GitHubT m) Source # | |
Defined in GitHub.REST.Monad | |
(MonadIO m, MonadFail m) => MonadGitHubREST (GitHubT m) Source # | |
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
|
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
The token to use to authenticate with GitHub.
Constructors
AccessToken ByteString | |
BearerToken ByteString |
GitHub Endpoints
data GHEndpoint Source #
A call to a GitHub API endpoint.
Constructors
GHEndpoint | |
Fields
|
type GitHubData = [KeyValue] Source #
type EndpointVals = [KeyValue] Source #
KeyValue pairs
A type representing a key-value pair.
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'.
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
HTTP standard method (as defined by RFC 2616, and PATCH which is defined by RFC 5789).
Instances
Bounded StdMethod | |
Enum StdMethod | |
Defined in Network.HTTP.Types.Method Methods succ :: StdMethod -> StdMethod # pred :: StdMethod -> StdMethod # fromEnum :: StdMethod -> Int # enumFrom :: StdMethod -> [StdMethod] # enumFromThen :: StdMethod -> StdMethod -> [StdMethod] # enumFromTo :: StdMethod -> StdMethod -> [StdMethod] # enumFromThenTo :: StdMethod -> StdMethod -> StdMethod -> [StdMethod] # | |
Eq StdMethod | |
Ord StdMethod | |
Read StdMethod | |
Show StdMethod | |
Ix StdMethod | |
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 |