Creating a GitHub Organization using GraphQL API

A few weeks ago, I came across an objective to create a GitHub organization leveraging API endpoints. After a lot of hustle, a solution was found taking the GraphQL API into consideration and thought of this as a great opportunity to give something back to the tech-community.

Introduction

The following sections will be reviewed in this article:

• GraphQL API
• Why use GraphQL API over the REST API?
• GraphQL query and mutation operations
• The GraphQL endpoint
• Hands-on Lab
• Conclusions
• References

GraphQL API

GraphQL is a query language for APIs that meets the demanding requirements of today’s frontend apps by fulfilling queries with our existing data. As an alternative to REST, GraphQL allows developers to construct requests that pull data from multiple data sources in a single API call.

Why use GraphQL API over the REST API?

GitHub does not have the provision to create an organization using the REST API; however, it has a GraphQL-endpoint available to perform the same. GitHub GraphQL API offers more precise and flexible queries than REST API, hence GraphQL becomes the choice.

GraphQL query and mutation operations

There are two types of operations allowed in GitHub’s GraphQL API

1. Queries — Operates like GET requests in REST API.
2. Mutations — Mutation name determines which modification is executed. It operates like POST/PATCH/DELETE in the REST API.

The GraphQL endpoint

GitHub GraphQL API has a single endpoint https://api.github.com/graphql

Without much ado, let’s get started!

Prerequisites

Before proceeding onto hands-on lab, we should ensure the below list of prerequisites.

1. GitHub Enterprise account
2. Postman tool — an API client
3. Authorization Mechanism — GitHub PAT [Personal Access token] with admin privileges

Hands-on Lab

Step 1: Login into GitHub Enterprise Account and jot down the Slug-Name of your GitHub enterprise. Here for my account it is “Glob-EMU”. Where slug is a URL-friendly version of a repository name.

Capture Slug-name of GitHub Enterprise

Step 2: Download the Public Schema for GitHub GraphQL from the below provided link — Public schema — GitHub Docs

Download public schema for GitHub GraphQL API

Step 3: Import Public Schema into Postman, which is an API client tool.

Open Postman and click on “Import” Tab

Import Public schema into Postman

Upload the public-schema-file, downloaded in step-2.

Close the prompt and observe a collection named “Postman Collection (from GraphQL)”. Kindly expand it, and you will witness GraphQL queries and mutations appearing inside your postman-collection.

Step 4: Retrieve GitHub Enterprise-ID using GraphQL Query operation.

Go to queries inside our collection and click on “enterprise”.

In the Authorization Section, update the authorization mechanism as a “bearer token” and enter GitHub PAT as value.

Retrieve GitHub Enterprise ID

Update the Slug-name of the enterprise we captured in Step-1, inside the “GraphQL variables” Body section, and send the request.

API Response will be shown as “200 OK” which is a standard response for successful HTTP requests. Capture the enterprise-ID from the API response, we will need this later.

Step 5: Now, let’s create a GitHub organization using mutation.

Go to mutations inside our collection and click on “createEnterpriseOrganization”.

In the Authorization Section, update the authorization mechanism as a “bearer token” and enter GitHub PAT as value.

Create GitHub Organization

Navigate to Body Section and update the GraphQL variables as described below

“adminLogins” — The Admin account through which we have created the GitHub PAT [Personal Access Token].

“billingEmail”: Email ID of the admin account

“enterpriseId”: ID of the Enterprise that owns the organization.

“Login” and “profileName”: Name of the organization to be created.

Send the request.

API Response will be shown as “200 OK”. GitHub Organization named “GlobPocOrganization should have been created in the GitHub enterprise account.

Step 6: Confirm the GitHub organization created in our enterprise account with name “GlobPocOrganization”.

GitHub Organization Created

Conclusions

GraphQL API helps us with the capability to resolve complex API-scenarios systematically and thus plays a vital role in creating GitHub organization, therefore owners and administrators can have a better control over member’s access to the organization’s data and projects with sophisticated security.

References

GitHub Organization — https://docs.github.com/en/organizations

GitHub GraphQL API — https://docs.github.com/en/graphql

“Spread the word like a wildfire!”