Software Engineering

Overview

GraphQL is an API query language used to obtain data from a server. It serves a similar purpose to a RESTful API, but with some distinct advantages.

The first advantage is that the you will only receive the data that you request. Part of the payload of a GraphQL request is the list of fields to return. This can help reduce load time for a request by only including the data that the consumer needs.

Another advantage of GraphQL is that you can get all the data you need in a single request. By defining the data you want from related fields, you can get all that data you need from those in one API call.

You can also very simply update the API without versioning. Adding new data to your endpoint will not cause any issues as the client will still only receive the data requested.

You can also use GraphiQL to test and document your API.

Example

Creating and consuming a GraphQL API is very simple. Let’s briefly go through setting up the server and then creating a simple client. In this article, we will be using Apollo and Node.js for the server, but GraphQL libraries are available in many languages.

First we need to define our data. We do this in GraphQL by defining type`s. Let’s consider a simple contact model:

type Contact {
name: String!
email: String!
}

This tells GraphQL that we have a type that is Contact that will include two strings, name and email. The next thing we need to do is define our queries:

type Query {
contacts: [Contact]
contact(name:String!): Contact
}

In this case we have two different queries. The first will return a list of Contacts and the other will return one Contact identified by the required name parameter.

Third we can define any Mutations that will allow for any changing of the data:

type Mutation {
addContact(name:String!, email:String!): Contact
}

The last step here is letting GraphQL know how to resolve these queries and mutations. To do this we will define resolvers:

var contacts = [
{name: "Test User", email: "test@user.com"},
{name: "Other User", email: "other@user.com"}
];
const resolvers = {
Query: {
contacts: () => contacts,
contact: (_, { name }) => contacts.find((c) => c.name === name)
},
Mutation: {
addContact: (_, { name, email }) => {
newContact = {name: name, email: email};
contacts.push(newContact);
return newContact;
}
}
};

Now all that is left is to hook it up. This depends on your exact setup, so I won’t go into detail. here.

Client

Creating a client to consume your new GraphQL endpoint is very simple.

Let’s create some GraphQL queries:

{
contacts{
name
email
}
}
query Contact($name:String!){
contact(name: $name){
name
email
}
}

Mutations will look something like this:

mutation addContact($name:String!, $email:String!) {
addContact(name: $name, email: $email) {
name
email
}
}

You can find a simple version of this application here: https://github.com/thomascking/graphql

More information: https://graphql.org/ https://www.apollographql.com/ https://www.robinwieruch.de/graphql-apollo-server-tutorial/