GitHub’s REST API was perfect. Now THIS is more perfect.
- GitHub’s GraphQL Endpoint
- Technologies to Access
- GitHub Documentation
- GitHub Auth Token
- Custom Graphene program
- Programmatic access
- More on API Microservices
- More about Git & GitHub
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:
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:
Facebook’s GraphQL (described by my article on GraphQL)
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:
Without installing anything: on a Terminal CLI crafting curl commands
TODO: Reference an OpenAPI (Swagger) spec file.
GitHub’s Developer Guide on GraphQL is at:
Notice there is a REST API and GraphQL API.
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.”
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).
Click your avatar image at the upper-right corner to be at:
Click “Developer settings” in the left menu to be at:
Click “Personal access tokens”.
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.
Check “Enterprise billing”, then “Save”
Click the clipboard icon to capture the key to your Clipboard.
Paste the key text in the Insomnia 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).
Click “OAuth Apps” to register a new OAuth GitHub app at:
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.
Register a new OAuth application
In the Deploy keys menu, click “Add deploy key”.
Be in your home user folder, which is never pushed to any public GitHub. Here is where you can keep files containing secrets.
PROTIP: Create a file named “.pygithub-secrets.env” containing your information instead of mine:
MY_GIT_USER_NAME="JohnDoe" MY_GIT_USER_EMAIL="email@example.com" MY_GITHUB_USER_NAME="JohnDoe" MY_GITHUB_PASSWORD="Pa$$w0rdisnotsecure" MY_GITHUB_TOKEN="23441234f13b1134c36667a"
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.
READ GitHub’s REST API documentation at:
Install client program Insomnia
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
Swagger can be generated from API definitions in Insomnia using Swaggymnia
There is a set of calls which can be loaded into Insomnia from:
That is v3 of GitHub’s API, which made individual REST calls.
“Imported Worspaces” categories, alphabetically:
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.
https://support.insomnia.rest/article/176-graphql-queries says Insomnia provides auto-completion and linting of GraphQL queries.
Custom Graphene program
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.
The app provides a UI to GitHub API calls made by the model_gh.py program.
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”.
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/
Visit https://github.com/PyGithub/PyGithub, which is now being maintained by Steve Kowalik, who works at SUSE in Syndey, Australia.
Docs on PyGitHub shows sample Python code. I modified it (with added notes) in my repo at:
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.
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.
When executed, the response from pygithub-hello.py is simply:
pip install pygithub is based on code:
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:
“Ariadne” using a SDL (Schema Definition Language) so less coding is needed.
More on API Microservices
This is one of a series:
- API Portals
- GraphQL API
- GitHub API
- GitHub GraphQL API
- API Swagger
- API Design Tools
- API Design
- API Programming
- REST API Responses
- API Management Evaluation
- API Management by Microsoft Azure
- API Management by Amazon
- PowerShell GitHub API Programming
- PowerShell API Programming
- PowerShell Desired State Configuration
- PowerShell on Mac
More about Git & GitHub
This is one of a series on Git and GitHub:
- Why Git? (file-based backups vs Git clone)
- Git basics (script)
- Git whoops (correct mistakes)
- Git command shortcuts
- Git interactive merge (imerge)
- Git patch
- Git utilities
- Git hooks
- GitHub data security
- GitHub REST API
- GitHub GraphQL API
- GitHub PowerShell API Programming
- GitHub GraphQL PowerShell Module