| Maintainer | Brandon Chinn <brandonchinn178@gmail.com> |
|---|---|
| Stability | experimental |
| Portability | portable |
| Safe Haskell | Safe-Inferred |
| Language | Haskell2010 |
GitHub.REST
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 (a, PageLinks)
- queryGitHub :: FromJSON a => GHEndpoint -> m a
- queryGitHubAll :: (FromJSON a, Monoid a) => GHEndpoint -> m a
- queryGitHub_ :: GHEndpoint -> m ()
- data GitHubT m a
- data GitHubSettings = GitHubSettings {}
- runGitHubT :: MonadIO m => GitHubSettings -> 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 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
Methods
queryGitHubPage :: FromJSON a => GHEndpoint -> m (a, PageLinks) Source #
Query GitHub, returning (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, if GitHub sent back an error message, or if the response could not be decoded as JSON. Use githubTry if you wish to handle GitHub errors.
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 | |
| MonadFail m => MonadFail (GitHubT m) Source # | |
Defined in GitHub.REST.Monad | |
| MonadIO m => MonadIO (GitHubT m) Source # | |
Defined in GitHub.REST.Monad | |
| Applicative m => Applicative (GitHubT m) Source # | |
| Functor m => Functor (GitHubT m) Source # | |
| Monad m => Monad (GitHubT m) Source # | |
| MonadIO m => MonadGitHubREST (GitHubT m) Source # | |
Defined in GitHub.REST.Monad Methods 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 # | |
| MonadUnliftIO m => MonadUnliftIO (GitHubT m) Source # | |
Defined in GitHub.REST.Monad | |
data GitHubSettings Source #
Constructors
| GitHubSettings | |
Fields
| |
runGitHubT :: MonadIO m => GitHubSettings -> 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
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).
Since: http-types-0.2.0