GraphQL — Yet Another API Spec? — Part 1
What does it offer to Native Developers?
GraphQL is a specification created by Facebook and they have open sourced it a few years ago. The promise of this specification is it will ease the development experience of both front-end mobile app developers and the server side API developers.
In this post, let’s find out whether GraphQL is yet another specification?
Does it solve the shortcomings of the existing API specifications like REST?
I promise by end of this series, you will have a clear understanding of the need for GraphQL and how it changes the native developer experience.
We will use practical examples to understand the GraphQL and how it differs from REST, We will use GitHub API V4, which is based on GraphQL. Refer here for the original announcement of GitHub adopting GraphQL.
Simple Queries with Complex Answers
Problem Statement
We want to create a native app page that lists the top 3 of repositories for the given user and the lists top 3 repository names of users that given user is following.
Let’s say given username is user A, the user A follows [user B, user C]
Let’s try to get the needed information with REST APIs of GitHub i.e. https://api.github.com V3.
In order to accomplish the results we need, we will have to call at least four APIs
- 1st is https://api.github.com/users/userA/repos to get the user A repositories
- 2nd is https://api.github.com/users/userA/following to get the user A followers
- 3rd is https://api.github.com/users/userA1/repos to get User B repositories
- 4th is https://api.github.com/users/userA2/repos to get User C repositories
What kind of data each of these API calls return?
You can use the postman to play with the APIs.
Type in the GET as https://api.github.com/users/{yourUserName}, substitute the {yourUserName} with your GitHub username
1st API response — that list the user repositories contains a lot of data, whereas we are interested only in repository names of the user A.
Have a look at the picture on your left, it is the much-simplified view of the sample data that you will get when querying for the list of repositories
We are getting around 90 data elements, where we need only the name of the repository. That’s a lot of unwanted data.
Let’s check the 2nd Query, use Postman. Type in the GET as
https://api.github.com/users/{yourUserName}/following
2nd API response that lists the users that user A follows also have plenty of data we don’t need. Have a look at the sample data for the followers below
Remember we are interested in only the below information
- Top 3 repositories name of user A
- Top 3 repositories name of the users that user A following
I am not listing the responses of repositories of user B and user C, it will be similar to the 1st API response — plenty of data we don’t need.
By this time you may have realized, the data we are getting from APIs are
- Over fetching — we get way too much data than we need
- Under fetching — We need to execute at least 4 queries to get the needed response, n+1 requests problem
- No metadata about the data being served
Complex Queries with Simple Answers
Let’s try to retrieve the same information using GraphQL.
Note: If you are new to GraphQL & don’t understand the syntax, don’t worry you will understand that eventually as part of the series.
Querying in GraphQL
We will use the GraphQL tools to understand the introspection, open the GitHub GraphQL explorer, in this editor you need to authenticate yourself with your GitHub account. Follow this link, when you need more help.
Copy paste the following query in the top left-hand window of the GraphQL explorer
For the parameters on the left-hand bottom side of the explorer, pass the data such as
The response will look similar to the below response
Things to be noted
No multiple server trips — in REST API, we need to call at least 4 times to accomplish the result.
You specify exactly what you need, no extra data, no over or under-fetching
Strongly Typed And Introspection
In the REST environment, we have a swagger editor that enables to understand the API.GraphQL provides a more intuitive tool that enables to introspect the API. We will use GitHub GraphQL explorer.
Let’s find out the other information that User type provides? Open the explorer and copy paste the below contents
Run the query, you should be able to introspect each type of the given API. Play with the tool, check other types such as Repositories.
By end of this exercise, I hope you will be able to appreciate the facts
- Introspection — gives you clear data about the API
- Clear specification of each element types — metadata about the endpoint is available for iterations
Strongly Typed
GraphQL schema is strongly typed, ensures querying APIs safer. Let’s understand with a practical example. Open the explorer and run the below query, this query will list the first five starred repositories.
For the parameters, pass your username such as
Now, try changing the line 3 text “starredRepositories(first: 5)” to string, such as “starredRepositories(first: “5”)”
Note the editor will show an error, still, run the query and see the results. you will see the error message similar to the below message.
The error message is super clear and very intuitive.
Single End Point Vs Multiple End Points
Unlike REST, GraphQL provides a single endpoint. The single endpoint provides you the nested data that spreads across multiple types. For example, in the previous query, we are able to query the user repositories and repositories of the users that given user follows as well in a single server trip.
So far we have seen the querying in GraphQL, in next post we will explore more about the query and how we can use GraphQL in a native app.
