In this article, I will be scratching the surface of GitHub API using GraphQL.
There are various reasons why GitHub chose the GraphQL API in its version 4, over its REST API, which was primarily the version 3. Before digging deep into the version 4, let us first talk about what GraphQL and Graph in GraphQL are.
What is GraphQL?
The Graph API is the primary way to get data into and out of the GitHub platform.
It's a low-level HTTP-based API that apps can use to programmatically query data, post new repositories, manage repositories, and perform a wide variety of other tasks.
According to the official document of GraphQL, following are
the four aspects of GraphQL, the data query language:
1. Specification
The specification determines the validity of the schema on the API server.
The schema determines the validity of client calls.
2. Strongly typed
The schema defines an API's type system and all object relationships.
3. Introspective
A client can query the schema for details about the schema.
4. Hierarchical
The shape of a GraphQL call mirrors the shape of the JSON data it returns.
Nested fields let you query for and receive only the data you specify in a single round trip.
What is a Graph in GraphQL?
The graph refers to graph structures defined in the schema,
where nodes define objects and edges define relationships between objects.
The API traverses and returns application data based on the schema definitions, independent of how the data is stored.
Why GitHub chose GraphQL over RestAPI?
According to the official documentation of GitHub:
GitHub chose GraphQL for our API v4 because it offers
significantly more flexibility for our integrators.
The ability to define precisely the data you want—and only the data you want—is a powerful advantage over the REST API v3 endpoints.
GraphQL lets you replace multiple REST requests with a single call to fetch the data you specify.
As I mentioned above that GraphQL is a query language, the question arises what the query is.
Query
Every GraphQL schema has a root type for both queries and mutations.
The query type defines GraphQL operations that retrieve data from the server.
GraphQL queries return only the data you specify.
To form a query, you must specify fields within fields (also known as nested subfields) until you return only scalars.
Queries are structured like this:
query {
objects to return
}
Now let us take an example to understand the API.
Example
query {
repository(owner:"octocat", name:"Hello-World") {
issues(last:20, states:CLOSED) {
edges {
node {
title
url
labels(first:5) {
edges {
node {
name
}
}
}
}
}
}
}
}
Let me explain them line by line:
-
Query block
- As I mentioned before that the query is actually used to
retrieve data from the server, therefore, in this case we would require a query to read data from the Github server.
Please note that the query is the root operation.
-
repository(owner:"octocat", name:"Hello-World") - if you go to the following link https://github.com/octocat you would see that the owner name is “octocat” and there is a repository called “Hello-World” as shown below.
-
issues(last:20, states:CLOSED) - This command is for all issues in the repository, we call the issues object. (We could query a single issue on a repository, but that would require us to know the number of the issue we want to return and provide it as an argument.)
-
edges - In order to retrieve data from the individual issues, we would need an edge. As we know issues is a connection because it has the IssueConnection type. To retrieve data about individual issues, we have to access the node via edges.
-
node - Here we retrieve the node at the end of the edge.
How to Run the Above Example
We would use Github’s API Explorer in order to run the above example.
Step 1
Go to the following link:
Step 2
Sign in using your GitHub account by clicking the button shown below:
Step 3
GitHub would ask you to authorize GitHub. Click the button shown below:
Step 4
Paste the following code in GraphiQL box:
query {
repository(owner:"octocat", name:"Hello-World") {
issues(last:20, states:CLOSED) {
edges {
node {
title
url
labels(first:5) {
edges {
node {
name
}
}
}
}
}
}
}
}
And click the play button, as shown below:
That’s it! Now you can see the following output of the code-mentioned above.
Output
If you have run it in the explorer, you would see the top twenty issues that were reported in that repository; their titles, url, labels everything you can access using GraphQL API.
Summary
In this article, we have explored the GitHub’s latest API using GraphQL. We have also learned how to access the repository using the GitHub’s explorer. In the future articles, I shall discuss in detail how each and every component works and how you can utilize GitHub’s API in different applications, like in your websites, iOS, Android etc. That’s it for this article!
