github-rest: Query the GitHub REST API programmatically

[ bsd3, github, library ] [ Propose Tags ]

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]
Versions [faq] 1.0.0, 1.0.1
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.2) [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 Fri Nov 1 20:09:34 UTC 2019
Distributions NixOS:1.0.1
Downloads 76 total (21 in the last 30 days)
Rating (no votes yet) [estimated by rule of succession]
Your Rating
  • λ
  • λ
  • λ
Status Hackage Matrix CI
Docs available [build log]
Last success reported on 2019-11-01 [all 1 reports]

Modules

[Index] [Quick Jump]

Downloads

Maintainer's Corner

For package maintainers and hackage trustees


Readme for github-rest-1.0.0

[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:

  • github-rest informs the user exactly which GitHub endpoint is being hit (e.g. /repos/:owner/:repo). Users no longer need to spend time trying to scour documentation to find the corresponding function for an endpoint.

  • github-rest passes authentication once, with requests executed in a single monadic context. The github package requires passing in an authentication token every time a request is executed

  • In the same vein, github-rest provides a monad transformer that handles all GitHub state needed to execute queryGitHub. github runs everything in IO, expecting the caller to keep track of GitHub state manually.

  • github-rest allows usage with aeson-schemas