I’ve heard a lot of talk about GraphQL and some very common misconceptions that come along with that recently. In this post I aim to describe what GraphQL is and how you might use it to build better software.
GraphQL isn’t a very recent technology. It was created by Facebook in 2012 and a few years later launched as a technical preview for developers to utilise in their own projects. In 2016 it became ‘production ready’ and the uptake of the technology is only increasing with time.
So what is it? GraphQL is both a query language used to communicate with a REST API and also a standard runtime which takes those queries and returns the data requested. It allows a developer to ask a REST API for what data they need and getting exactly that back.
Hypothetically, you may have to query multiple endpoints to find a list of communication methods for employees in an imaginary HR System. This could be; a call to list all employees to establish their IDs, a call to list each employee’s communication IDs given an employee ID and perhaps even a call to a communications endpoint to list each communication. The problem is further complicated becuse when I grab employees, I might also get back their names, addresses, department, position and more which I will just throw away becasue I don’t care about it. Of course, I can design an API around these issues but in that case I am orchestrating endpoints for specific business requirements which is an architectural nightmare.
With GraphQL I can write a query that will ask for a list of communication methods against employees and in one call, the server will return just the correct data.
Before I dive into the strengths and weaknesses of the technolgoy, let’s just take a look at what a request looks like and what it might return. To start with, the below GraphQL is asking for the firstName and communication methods of all employees.
{
employees {
firstName
communications {
communicationType,
detail
}
}
}This is returned as the below JSON. You can see each employee is listed with the firstName and communications show the communicationTpye and detail just as I asked.
{
"data": {
"employees": [
{
"firstName": "Adam",
"communications": [
{
"communicationType": "Mobile",
"detail": "0123456789"
},
{
"communicationType": "Website",
"detail": "www.theadamblog.co.uk"
}
]
},
{
"firstName": "Karen",
"communications": [
{
"communicationType": "Email",
"detail": "example.email@test.com"
},
{
"communicationType": "Mobile",
"detail": "0987654321"
}
]
}
]
}
}Why use GraphQL?
There are many great features to GraphQL which I will explore over future blog posts. I have already highlighted the simple query syntax which allows you to access just the data you need from the API, but this comes with a massive advantage in that applications tend to be quicker as less processing is needed by both the server and the client. Data is significantly smaller in size and far fewer requests need to be made.
GraphQL also allows you to access multiple resources in one request. This is ideal for apps which run on a mobile connection and may not be able to send multiple requests in succession as quickly.
There are other featuers of the runtime that you can come to expect from any good query language; schema definitions, arguments, variables and the ability to update data on the server using a feature called mutations. I’ll explore each of these in a later post too.
What backend framework?
GraphQL is simply a specification of data transfer and is therefore platform agnostic. You can use many libraries which will assist you with you with different languages. These range from JavaScript implementations throguh to Go, Flutter, Python and of course C# / .NET.
This means that, like SQL, you can use this across many projects and services in your application which can be written in different technologies. Note that these are community based projects and may not be official implementations.
Summary
I’ve only touched the surface of GraphQL but I will explore the rest of the framework in future posts. I have highlighted how you can write a signle requests for mutliple different entities and request only the data you need.
I think one of the massive benefits of it shows that it can be fast in accessing data, returning data and in turn makes your applications quicker at processing data. The fact it can be written in any technology stack means it’s a great fit for microservice architecture.