github-rest: Query the GitHub REST API programmatically

This is a package candidate release! Here you can preview how this package release will appear once published to the main package index (which can be accomplished via the 'maintain' link below). Please note that once a package has been published to the main package index it cannot be undone! Please consult the package uploading documentation for more information.

[maintain] [Publish]

Query the GitHub REST API programmatically, which can provide a more flexible and clear interface than if all of the endpoints and their types were defined as Haskell values.


[Skip to Readme]

Properties

Versions 1.0.0, 1.0.1, 1.0.2, 1.0.2, 1.0.3, 1.1.0, 1.1.1, 1.1.2
Change log CHANGELOG.md
Dependencies aeson (>=1.1.2.0 && <1.5), base (>=4.9 && <5), bytestring (>=0.10.8.1 && <0.11), http-client (>=0.5.13.1 && <0.7), http-client-tls (>=0.3.5.3 && <0.4), http-types (>=0.12.1 && <0.13), jwt (>=0.9.0 && <0.11), mtl (>=2.2.2 && <2.3), scientific (>=0.3.6.2 && <0.4), text (>=1.2.2.2 && <1.3), time (>=1.8.0.2 && <1.10), transformers (>=0.5.2.0 && <0.6), unliftio (>=0.2.7.0 && <0.3), unliftio-core (>=0.1.1.0 && <0.3) [details]
License BSD-3-Clause
Author Brandon Chinn <brandon@leapyear.io>
Maintainer Brandon Chinn <brandon@leapyear.io>
Category GitHub
Home page https://github.com/LeapYear/github-rest#readme
Bug tracker https://github.com/LeapYear/github-rest/issues
Source repo head: git clone https://github.com/LeapYear/github-rest
Uploaded by leapyear at 2020-03-02T20:06:38Z

Modules

[Index] [Quick Jump]

Downloads

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees


Readme for github-rest-1.0.2

[back to package description]

github-rest

CircleCI Hackage

A package providing a more flexible interface to accessing the GitHub API. Endpoints are created using the GHEndpoint constructor and are executed with the queryGitHub function in the GitHubT monad.

Quickstart

This quickstart will demonstrate querying endpoints in a hypothetical public GitHub repo alice/my-project.

{-# LANGUAGE OverloadedStrings #-}
{-# OPTIONS_GHC -fno-warn-type-defaults #-}

import Data.Text (Text)
import GitHub.REST
import Network.HTTP.Types (StdMethod(..))

default (Text)

main = do
  let state = GitHubState
        { token = Nothing
          -- ^ An authentication token to use, if any.
        , userAgent = "alice/my-project"
          -- ^ GitHub requires this to be set to a User Agent specific to your
          -- application: https://developer.github.com/v3/#user-agent-required
        , apiVersion = "v3"
          -- ^ Specifies the API version to query: https://developer.github.com/v3/media/
        }

  runGitHubT state $ do

    -- Get information for the "master" branch
    -- https://developer.github.com/v3/git/refs/#get-a-single-reference
    ref <- queryGitHub GHEndpoint
      { method = GET
        -- Colon-prefixed components in the endpoint will be interpolated by
        -- the values in 'endpointVals'.
        -- In this case, "/repos/alice/my-project/git/refs/heads/master"
      , endpoint = "/repos/:owner/:repo/git/refs/:ref"
      , endpointVals =
        [ "owner" := "alice"
        , "repo" := "my-project"
        , "ref" := "heads/master"
        ]
      , ghData = []
      }

    -- 'github-rest' provides a '.:' helper for when the API guarantees that a
    -- key in a JSON object exists
    --
    -- The result of 'queryGitHub' is anything that's an instance of FromJSON,
    -- if using manually-defined data types is preferred over using '.:'. This
    -- package can be easily used with the aeson-schemas library, which
    -- provides a type-safe way to query JSON data.
    let sha :: Text
        sha = ref .: "object" .: "sha"

    -- Create a new branch called "foo"
    -- https://developer.github.com/v3/git/refs/#create-a-reference
    queryGitHub GHEndpoint
      { method = POST
      , endpoint = "/repos/:owner/:repo/git/refs"
      , endpointVals =
        [ "owner" := "alice"
        , "repo" := "my-project"
        ]
      , ghData =
        [ "ref" := "refs/heads/foo"
        , "sha" := sha
        ]
      }

Comparison to other libraries

The github package provides a decent API for querying the GitHub API, and it defines Haskell data types for each endpoint. These data types can be used as the result of queryGitHub.

This package provides a different interface for people with different tastes: