Wilson Mar bio photo

Wilson Mar

Hello!

Email me Calendar Skype call

LinkedIn Twitter Gitter Instagram Youtube

Github Stackoverflow Pinterest

GitHub’s REST API was perfect. Now THIS is more perfect.

US (English)   Español (Spanish)   Français (French)   Deutsch (German)   Italiano   Português   Cyrillic Russian   中文 (简体) Chinese (Simplified)   日本語 Japanese   한국어 Korean

Overview

This article covers working with GitHub’s GraphQL by manually issuing single requests and by programming.

GitHub’s GraphQL Endpoint

GitHub provides a well-known GraphQL API end-point which accepts a lot of traffic for all operations:

    https://api.github.com/graphql

GitHub was among the first to adopt GraphQL’s leading-edge API techniques, so their APIs are referenced as an example industry-standard we would do well to emulate:

I first looked at GitHub’s GraphQL API in 2016 during their https://developer.github.com/early-access/graphql/ which included the https://developer.github.com/early-access/graphql/explorer/

Technologies to Access

As with any API, there are several ways you can there make calls:


GitHub Documentation

  1. GitHub’s Developer Guide on GraphQL is at:

    https://developer.github.com/v3/guides/getting-started

    Others:

    • https://developer.github.com/enterprise/2.20/
    • https://developer.github.com/enterprise/2.20/apps/
      Building apps

  2. Click https://docs.github.com/en

    Notice there is a REST API and GraphQL API.

  3. Click “GraphQL API” at https://docs.github.com/en/graphql

    “to create precise and flexible queries for the data you need to integrate with GitHub.”

  4. Get a GitHub account if you don’t already have one.

    GitHub’s guides provide sample API calls using the curl command-line utility.

    GitHub Auth Token

    Even working on public repos, unauthenticated clients can make only 60 requests per hour and see limited informaiton unless you get an authentication token to make a call like this:

    curl -i -H "Authorization: token 5199831f4dd3b79e7c5b7e0ebe75d67aa66e79d4" \
     https://api.github.com/user/repos
    

    -H specifies the token in the HTTP header (which is more secure than in Query parameters).

  5. Click your avatar image at the upper-right corner to be at:

    https://github.com/settings/profile

  6. Click “Developer settings” in the left menu to be at:

    https://github.com/settings/developers

  7. Click “Personal access tokens”.

    VIDEO and this blog explains the steps for generating a PAT for Insomnia to use as a bearer authentication token. It references this GitHub doc.

    PROTIP: Remember that a PAT (Personal Access Token) is the same as your account password which grants full access to all your repositories within your account.

  8. Check “Enterprise billing”, then “Save”

    github-ent-data-chk-406x76

  9. Click the clipboard icon to capture the key to your Clipboard.

  10. Paste the key text in the Insomnia app.

    OAuth App

    An “OAuth App” (such as Insomnia) acts as a GitHub user.

    A “GitHub App” uses its own identity installed on an organization (granted by an organization administrator).

  11. Click “OAuth Apps” to register a new OAuth GitHub app at:

    https://github.com/settings/applications/new

    graphql-oauth-form-592x496

    READ: https://docs.github.com/en/developers/apps/differences-between-github-apps-and-oauth-apps

  12. Navigate to the Settings page of the repo you want to use APIs on.

    NOTE: You need to be an owner or Administrator to see “Settings” tab.

    Deploy keys limits access to a specific repository in your account using SSH.

  13. Register a new OAuth application

    https://github.com/settings/applications/new

    See https://docs.github.com/en/rest/guides/basics-of-authentication

    https://docs.github.com/en/rest/reference/repos#create-a-repository-for-the-authenticated-user

  14. In the Deploy keys menu, click “Add deploy key”.

  15. Be in your home user folder, which is never pushed to any public GitHub. Here is where you can keep files containing secrets.

  16. PROTIP: Create a file named “.pygithub-secrets.env” containing your information instead of mine:

    MY_GIT_USER_NAME="JohnDoe"
    MY_GIT_USER_EMAIL="johndoe@gmail.com"
    MY_GITHUB_USER_NAME="JohnDoe"
    MY_GITHUB_PASSWORD="Pa$$w0rdisnotsecure"
    MY_GITHUB_TOKEN="23441234f13b1134c36667a"
    
  17. If you’re using GitHub Enterprise behind the Okta identity provider (IdP) for SSO (Single Sign On), you will need to be given access that instance an probably have to install a VPN client as well.

    https://help.github.com/en/github/authenticating-to-github/about-authentication-with-saml-single-sign-on

  18. READ GitHub’s REST API documentation at:

    https://help.github.com/en/github/setting-up-and-managing-organizations-and-teams/about-identity-and-access-management-with-saml-single-sign-on

    https://medium.com/swlh/introduction-to-graphql-with-github-api-64ee8bb11630

    Install client program Insomnia

  19. PROTIP: Instead of downloading from https://insomnia.rest/download, install Insomina into the ~/Applications folder on your Mac, using Homebrew:

    brew install --cask insomina
    

    Alternately, on Windows within Git Bash run as Administrator (with elevated privileges), use Chocolatey:

    choco install -y insomina-rest-api-client
    

    NOTE: Insomnia is built using GitHub’s Electron, which enables coding of JavaScript to generate programs running on macOS and Windows. Insomnia is MIT open-sourced at https://github.com/Kong/insomnia

    Swagger can be generated from API definitions in Insomnia using Swaggymnia

    v3 GraphQL

  20. There is a set of calls which can be loaded into Insomnia from:

    https://github.com/swinton/github-rest-apis-for-insomnia

    That is v3 of GitHub’s API, which made individual REST calls.

    “Imported Worspaces” categories, alphabetically:

    • activity
    • apps
    • checks
    • codes-of-conduct
    • emojis
    • gists
    • git
    • gitignore
    • interactions
    • issues
    • licenses
    • markdown
    • meta
    • migrations
    • oauth-authorizations
    • orgs
    • projects
    • pulls
    • rate-limit
    • reactions
    • repos
    • scim
    • search
    • teams
    • users

    PROTIP: GraphQL is V4 of GitHub’s API. GraphQL calls can request any of the above categories of data in a single call. Conversion to GraphQL saved Github, Facebook, and others tremendously reduced traffic, bandwidth, and server processing load.

    v4 GraphQL

    https://support.insomnia.rest/article/176-graphql-queries says Insomnia provides auto-completion and linting of GraphQL queries.

    BLOG: https://medium.com/swlh/introduction-to-graphql-with-github-api-64ee8bb11630


Custom Graphene program

GraphQL

https://github.com/graphql-python/gql is a GraphQL client for Python. Plays nicely with graphene, graphql-core, graphql-js and any other GraphQL implementation compatible with the spec.

Flask app

The app provides a UI to GitHub API calls made by the model_gh.py program.

Pavel Prudký (from Prague) shared his Python Flask mvc app to list/manage GitHub branches and files on his GitHub:

github-flask-app-665x409.png

Programmatic access

Programs program enable automated preparation of calls and handling of results (looping through a list, saving to a database, etc.).

People have open-sourced libraries of code so you don’t have to “reinvent the wheel”.

Ruby

Internally, GitHub was orginally written in Ruby. Thus: https://developer.github.com/enterprise/2.20/apps/quickstart-guides/using-the-github-api-in-your-app/

Javascript

GitHub’s ProBot is written in TypeScript language for NodeJs, is a framework to extend the functionality of GitHub, such as these, listed by number of stars.

Python

  1. Visit https://github.com/PyGithub/PyGithub, which is now being maintained by Steve Kowalik, who works at SUSE in Syndey, Australia.

  2. Docs on PyGitHub shows sample Python code. I modified it (with added notes) in my repo at:

    https://github.com/wilsonmar/python-samples/blob/master/pygithub-hello.py

    The above repo is private. Ask me about making you a collaborator.

    My version of the code references system variables so that secrets are not stored in code on public GitHub.

  3. Looking at the code, the program looks for that default file name holding secrets if there is no override file specified with the program execution call. If neither is found, the program falls back to reading individual environment variables.

    pygithub.sh
  4. When executed, the response from pygithub-hello.py is simply:

    pip install pygithub is based on code:

  5. Make sample Python calls

    The canonical websit on GraphQL has sample Python code: https://graphql.org/code/#python

Want your own GraphQL server?

You may want a custom (proxy) server responding to requests from your company’s apps, so they don’t all have to make calls to GitHub.

This may be because you don’t want to grant every program access to all information, which is what GitHub currently does. GitHub doesn’t limit the content of data accessed by a token, only categories of their services.

A custom server would enable you to respond any way you want. (But you also have to worry about providing enough capacity, unlike a SaaS offering like GitHub)

There are two major Python code library for implementing GraphQL servers:

The Graphene Python library takes a “code-first” approach:

https://docs.graphene-python.org/en/stable/quickstart

“Ariadne” using a SDL (Schema Definition Language) so less coding is needed.

https://ariadnegraphql.org/ describes https://github.com/mirumee/ariadne

More on API Microservices

This is one of a series:

More about Git & GitHub

This is one of a series on Git and GitHub:

  1. Git and GitHub videos

  2. Why Git? (file-based backups vs Git clone)
  3. Git Markdown text

  4. Git basics (script)
  5. Git whoops (correct mistakes)
  6. Git messages (in commits)

  7. Git command shortcuts
  8. Git custom commands

  9. Git-client based workflows

  10. Git HEAD (Commitish references)

  11. Git interactive merge (imerge)
  12. Git patch
  13. Git rebase

  14. Git utilities
  15. Git-signing

  16. Git hooks
  17. GitHub data security
  18. TFS vs GitHub

  19. GitHub actions for automation JavaScript
  20. GitHub REST API
  21. GitHub GraphQL API
  22. GitHub PowerShell API Programming
  23. GitHub GraphQL PowerShell Module