Introduction to GraphQL with GitHub API
Understand the main advantages of GraphQL exploring the GitHub API.
GraphQL is a new API standard that provides a more efficient, powerful, and flexible alternative to REST. It's is a specification to a query language and a server-side runtime for executing queries by using a type system you define for your data. This means that we have a more declarative way to get data from service. This is the same paradigm that you can see at SQL when searching for data at a database.
GraphQL provides a complete and understandable description of the data in your API, gives clients the power to ask for exactly what they need and nothing more, makes it easier to evolve APIs over time, and enables powerful developer tools.
For an easier introduction, it would be nice if there were a GraphQL API easy to access and with good documentation. Luckily, GitHub chose GraphQL for your API version 4. The GitHub API allows you to get data about repositories, users, issues, and a lot of other things. It's a good tool when you want to explore some technology and don't want to use mock data or create an API from scratch. Just like in this article!
What you will learn in this article?
- The main advantages of GraphQL over REST.
- How to connect to Github GraphQL API.
- How works GraphQL PlayGround: A tool like Insomnia and Postman to easily consume GraphQL APIs.
The REST API problem
REST is the more used standard to create and consume API, so if you integrated a web or mobile app with some backend application, it's almost certain that you have used a REST API. And if you needed some more complex data you had to do a lot of requests to different endpoints. To see more clearly this problem. Let's get some information about the React repository with GitHub API.
If we also want to get data about the issues we need more than one request.
In the above code, probably the repository and issues constants have more data than you need. This is because the endpoints have to satisfy many different situations and with REST APIs there is no simple way to defined the data that you want.
To resolve this and some more challenges that GitHub build your v4 API with the GraphQL specification.
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.
First Request
When we want to test or explore some REST API, we usually use some tools like Insomnia or Postman. In GraphQL we have a good tool called GraphQL Playground that allows it to connect and consume APIs. I will use here the Desktop version, but there is a Web version too.
In the GraphQL APIs, we have only one endpoint that is configured at first, so all request is over this URL. To Github API the endpoint is https://api.github.com/graphql.
After download and open the GraphQL Playground, the first screen asks to create a Workspace, that can be local or a URL endpoint. Then select the URL ENDPOINT option and paste de Github endpoint, like the image below.
Clicking on the open button, you see a problem: Authentication. Differently from Github REST API, which allows us to do up to 60 requests an hour without authentication, GitHub only allows requests at GraphQL API when it's has a token to authentication.
Creating access token to GitHub API
To get a token you need a GitHub account. On your profile, go to Settings, at the left side of the page click at Developer Settings, then Personal access tokens, and finally click on Generate new token button.
Now you can get a token and use at GraphQL Playground. If you need more information about the generation token process, you can access the GitHub help section:
Now you add this token at the header of your request, so you have access to GitHub API. At GraphQL Playground you need to add a Bearer token at the HTTP Header tab.
Replace YOUR_TOKEN in the code above and click at the Play button in the center of the screen:
Looking at the right side of the image above, you have two tabs: SCHEMA (definition of all system type) and DOCS. This second will be your guide about the requests that you can do at this GraphQL API. In this tab, the requests are separated into two, QUERIES (get data) and MUTATION (create, update, and delete data). Those are the most common operations that you do when interacting with a GraphQL API. They are like substitutes to the HTTP methods GET, POST, PUT, and DELETE. If you wanna know more about its highly recommend read the GraphQL documentation, there are a lot of examples easy to understand and with great descriptions.
Now that you know the basic concepts, you are ready to do your first query and get some data about GitHub repositories. And already here, you see a great adventure of GraphQL APIs, when the developers build de API, they need to define types and field on those types, then provide functions for each field on each type. Thanks to that we have all data that comes from API documented, and libraries or tools like GraphQL Playground can take advantage of that to improve the development experience.
Get data from React repository
Now we are going to create a query that will get data about a repository. We will call the query object of GetRepository (you are free to choose any name).
This query object uses a predefined query called repository. This query receives two parameters: owner and name. In this example, we are using the React repository. We also explicitly specified the data that we want (id, nameWithOwner, description, and url). Remember that all queries, field, and parameters are available and documented at the SCHEMA and DOCS tab. In the following code, we can see de JSON response from API.
See side by side in the GraphQL Playground:
If you want more details about how I built this query using GraphQL Playground autocomplete, check the video (24 seconds). The tools only can make these suggestions because GraphQL uses a strong type system to define the capabilities of an API. To see suggestions use the control + space shortcut.
Get data about repository and Issues
What if you also want data about the issues? With GraphQL you don't need two or more requests, you only need to specify the data that you want in the same query.
In the above query, we were deeper, we get data about issues (totalCount), get de last 2 issues with title and creation date (createdAt), and also data about the issue author. To get the same result at RESP API it would be necessary 2 requests and get a lot of data that it's not necessary at this moment.
With GraphQL you get all you need and only you need with just one request!
Conclusion
GraphQL has a substantial adoption difficulty because needs backend and frontend implementations, but despite that, I believe that is a technology that will become very popular in the next years. If you have more curiosities about, I hight recommend watch this great HoneyPot documentary with the Facebook engineers that created GraphQL.
There are a lot of other things to talk about this new way to consume and build APIs, but this article would be too big. I plan to write more about GraphQL, talk about mutations, integration with React application, and more. If you would like to see this or have any questions, please leave a comment. I hope I helped you in some way, thanks for your time!
