API (application programming interfaces), you most likely know what these are, you have worked with them before. A client or user can request data from a web service. A typical REST API lists out a bunch of endpoints where you may ask for several types of resources and while you ask for a resource from this endpoint, you get that type of thing after which if you need a unique kind of resource, you have to ask it from a different endpoint.

Queries

So you have most likely used database queries earlier than utilizing some type of query language like Sequel (SQL) or know Sequel language.

You can ask for something like,

Hey, give me the titles of the First 10 movies in Netflix

That’s in your database and the number of users that have watched each one.

So, you have a question, you formulate a query, write it in this language that the database knows how to execute and then the database sends you back that data that you requested.

GraphQl vs Other Rest APIs

Queries are different from how we normally think of APIs about getting data from APIs. But what if you could do that? What if you said to an API, I want this kind of data and only this data. Don’t send me back everything you have related to this resource, just this thing that I have in the query.

GraphQL

Graphic credit – https://blog.apollographql.com/how-do-i-graphql-2fcabfc94a01

So if you had a queryable API, you could ask for what you need, you could get things across different resources like a join in a database to give you different types of objects and you only get the stuff that you ask for. So, the concept of queryable APIs is not particularly new.

But, in practice, a lot of APIs don’t provide these options. There’s also Odata, a specification that’s used mostly by SAP and Microsoft and you can do similar things. It’s also built upon rest. And you can say select these fields just like in a database query or expand these fields and get these related resources.

There are also other ones like JSON API and probably lots more that people have come up with over the years. But lately, there’s been a lot of talk about this new thing called GraphQL and that’s why you’re here so you’ve probably heard about it before. But it might mostly just sound like a buzzword to you.

Let’s look at what GraphQl actually is.

So, it is an API query language. It’s not any particular library or framework or technology. It’s essentially a language and other people can build libraries to support that language. Just like SQL is a language and then you have different implementations like MySQL and Postgres.

It was created by Facebook in 2012 and it was eventually opened up to the public and open sourced in 2015. And since then, there’s been a lot of talk about it and a lot of adoption, both with small startups and large companies, alike. So currently, GitHub is one of the biggest well-known users of GraphQL but also companies like Yelp and Intuit and I think currently Airbnb are moving toward GraphQL APIs.

You can get more information here.

So, what does it look like? Here is an example of a query that you could give to, in this example, the GitHub API.

Request (query)

{
user ( login: "John Doe"){

name
location
}

}

Response



{

"data": {

"user": {
 
"name": "JoHn Doe",
"loctation": "Pithoragarh, UK, India",

}
}
}

So you can see that the request is kind of JSON-like and then the response is JSON. Now it doesn’t have to be JSON but the query language was built around a JSON response so that’s what is a common method of using it.

So, in this example, I’m asking for a user and filtering based on the user with the login John DOE. So that’s my GitHub user. And I want the name and location of that person. And as you can see in the response, that’s exactly what I get.

So you can see that it’s a very intuitive language, maybe, I would say more intuitive than using query parameters to get the same kind of information because what you’re asking for it is in the same shape as what you’re getting back and it’s pretty human readable and understandable. There are nesting and stuff. So it’s a lot more accessible and that’s the big reason why people are drawn to it now instead of these other methods. That was for querying data and getting data.

GraphQL also has the ability to update data and they do that using something called mutations. And this is an example of what a very simple mutation might look like. So instead of doing a delete request, you would send a query that’s a mutation to delete a user, give it some input so it knows which one to delete and then also get some data returned from that mutation.

So in this case, just the response that it actually was deleted. But it could be more complicated than that. And that’s basically the gist of what GraphQL is.

To run a GraphQL.js hello world script from the command line:

npm install graphql

Then run node hello.js with this code in hello.js:



var { graphql, buildSchema } = require('graphql');

var schema = buildSchema(`
  type Query {
    hello: String
  }
`);

var root = { hello: () => 'Hello world!' };

graphql(schema, '{ hello }', root).then((response) => {
  console.log(response);
});

Conclusion

GraphQL is a language for talking to an API and saying what you want to do and it gives a lot more control to the client. It’s really another technology for your tool belt that you can use when the right situation arises.