What is GraphQL?
Usually, APIs are designed using the RESTful design. The REST or “Representational State Transfer” protocol describes how APIs usually behave. Programmers are familiar with making rest APIs, setting up request objects for complex objects using special endpoints, and asking for the files you need in the request body. The fundamental flaw with this is you'll usually get a large object back, with lots and lots of data that you don't need, and a few pieces that you do. Then the background magic of nodeJS garbage collection clicks in and the data you don't need goes away forever and your program can keep doing its thing.
The fundamental flaw with this is that at scale, all of that data wasted really didn't need to be sent over the network, garbage collection shouldn't have had to deal with it, and there’s gotta be a better way! Right? That's where GraphQL comes in.
Here’s an example REST API call to an API to get my repositories off of Github. Let’s assume I just need the names of my repositories.
Here are the first 50 lines of response, remember I just want the names.
{"id": 336057448,"node_id": "MDEwOlJlcG9zaXRvcnkzMzYwNTc0NDg=","name": "bc_practice_test","full_name": "Rogersiver/bc_practice_test","private": false,"owner": {"login": "Rogersiver","id": 21316328,"node_id": "MDQ6VXNlcjIxMzE2MzI4","avatar_url": "https://avatars.githubusercontent.com/u/21316328?v=4","gravatar_id": "","url": "https://api.github.com/users/Rogersiver","html_url": "https://github.com/Rogersiver","followers_url": "https://api.github.com/users/Rogersiver/followers","following_url": "https://api.github.com/users/Rogersiver/following{/other_user}","gists_url": "https://api.github.com/users/Rogersiver/gists{/gist_id}","starred_url": "https://api.github.com/users/Rogersiver/starred{/owner}{/repo}","subscriptions_url": "https://api.github.com/users/Rogersiver/subscriptions","organizations_url": "https://api.github.com/users/Rogersiver/orgs","repos_url": "https://api.github.com/users/Rogersiver/repos","events_url": "https://api.github.com/users/Rogersiver/events{/privacy}","received_events_url": "https://api.github.com/users/Rogersiver/received_events","type": "User","site_admin": false},"html_url": "https://github.com/Rogersiver/bc_practice_test","description": "Practice exam for Bootcamp Class","fork": true,"url": "https://api.github.com/repos/Rogersiver/bc_practice_test","forks_url": "https://api.github.com/repos/Rogersiver/bc_practice_test/forks","keys_url": "https://api.github.com/repos/Rogersiver/bc_practice_test/keys{/key_id}","collaborators_url": "https://api.github.com/repos/Rogersiver/bc_practice_test/collaborators{/collaborator}","teams_url": "https://api.github.com/repos/Rogersiver/bc_practice_test/teams","hooks_url": "https://api.github.com/repos/Rogersiver/bc_practice_test/hooks","issue_events_url": "https://api.github.com/repos/Rogersiver/bc_practice_test/issues/events{/number}","events_url": "https://api.github.com/repos/Rogersiver/bc_practice_test/events","assignees_url": "https://api.github.com/repos/Rogersiver/bc_practice_test/assignees{/user}","branches_url": "https://api.github.com/repos/Rogersiver/bc_practice_test/branches{/branch}","tags_url": "https://api.github.com/repos/Rogersiver/bc_practice_test/tags","blobs_url": "https://api.github.com/repos/Rogersiver/bc_practice_test/git/blobs{/sha}","git_tags_url": "https://api.github.com/repos/Rogersiver/bc_practice_test/git/tags{/sha}","git_refs_url": "https://api.github.com/repos/Rogersiver/bc_practice_test/git/refs{/sha}","trees_url": "https://api.github.com/repos/Rogersiver/bc_practice_test/git/trees{/sha}","statuses_url": "https://api.github.com/repos/Rogersiver/bc_practice_test/statuses/{sha}","languages_url": "https://api.github.com/repos/Rogersiver/bc_practice_test/languages","stargazers_url": "https://api.github.com/repos/Rogersiver/bc_practice_test/stargazers","contributors_url": "https://api.github.com/repos/Rogersiver/bc_practice_test/contributors","subscribers_url": "https://api.githu
I JUST NEED THE NAMES! This is inefficient and If I had to make this call a million times a day my bill would be quite large.
Here’s the same call in GraphQL
query {
viewer {
repositories(first: 5) {
edges {
node {
name
}
}
}
}
}Heres the response
{
"data": {
"viewer": {
"repositories": {
"edges": [
{
"node": {
"name": "rogersiver.github.io"
}
},
{
"node": {
"name": "lodown"
}
},
{
"node": {
"name": "bc_practice_test"
}
},
{
"node": {
"name": "greenlight-notes"
}
},
{
"node": {
"name": "twiddlr"
}
}
]
}
}
}
}I asked for the names, I got the names. No use for links and ids that are just going to get deleted somewhere. GraphQL is clean and eliminates data waste, which as projects scale scales as an issue. The queries that make the internet work could contain much less data, and be much more efficient. I am excited to use GraphQL on future projects.
Another key difference between REST and GraphQL is that you need some sort of third-party host for GraphQL, instead of being able to do requests with Postman, cURL, or Axios. For my last project, I used Apollo with GraphQL express; but urQL (‘Urkle’), Hasura, and GraphQL yoga are all great options. In the case of Apollo, they provided my team with the ability to map queries straight out to existing database entities, and use those queries/mutations with extremely easy to implement react hooks. This makes the API experience more like using a product, rather than building one from scratch, with all of the power of such. Migrating to GraphQL will save bandwidth, client and server processing power, programming time, documentation writing time, the list goes on. Definitely using GraphQL on future projects.
