Introduction to GraphQL with Ballerina

Want to do more with fewer API calls?

GraphQL has become a prominent technology for implementing data APIs because it provides a convenient and intuitive approach for querying data. It solves potential problems such as data over-fetching and high latency that you may notice in traditional data services.

What is GraphQL?

So you may know REST architecture. I could say that most of the modern application network architecture is based on REST, It basically uses HTTP calls to get and modify data over the network. Commonly used actions include GET, POST, PUT and DELETE. Even though this is a very cool thing there are some disadvantages to it when considering a large-scale application. Let me explain.

Let’s say you have a set of API endpoints to get some data related to an employee management system and you have a database with a very large number of datasets as well. For example, you need the record of employee Sam’s personal details such as an address, contact number, and salary. How you going to address this issue is simply you get the employee list and go through that and find Sam and then get his ID and finally query the salary table and get the data related to that ID. This is the normal approach. Imagine you have millions of data records, you will face some major issues here.

1. It will fetch all the data whether required or not. This is called over-fetching.
2. It needs multiple network calls to complete a simple job.
3. In some cases, it might not fetch the data you need (Similar to 2nd point above) and it’s called under-fetching.

To address these issues, Facebook came up with a really cool solution called GraphQL, an open-source data query and manipulation language for APIs.

Why use GraphQL?

There are many reasons why you need to consider using GraphQL for your project. Mainly,

• It prevents data from over fetching and under fetching as I said. So you can have exactly what you need. Nothing less, nothing more.
• GraphQL has a strongly-typed schema. We can define what type of data records are supported by our API. It will help the developer to easily understand how to use the network calls. The most basic components of a GraphQL schema are object types, which just represent a kind of object you can fetch from your service, and what fields it has. In the GraphQL schema language, we might represent it like this:

type Employee {
  id: String!
  name: String!
  phone: String!
  age: Int!
}

• Saves time and Bandwidth. As I mentioned earlier using graphQL we can eliminate multiple calls to complete a single job done. So we can do a lot in a single query call. One of the major reasons why Facebook came up with this was most of the Facebook users used mobile devices and it was not guaranteed to have solid network connectivity all the time, so graphql helped to run query calls with less bandwidth as well. So win-win.

Ballerina-GraphQL

Oh, I forgot to mention that you can use a number of programming languages to write your graphql server but I like Ballerina the most because it is very simple to write and understand the schemas and types using Ballerina. It is a programming language that has GraphQL as part of its built-in language-level services support.

https://wso2.com/graphql-apis

In Ballerina, the GraphQL object structure is modeled using services. A Ballerina GraphQL service contains resource methods that map to the fields of the GraphQL objects and work as resolver functions to provide its data. The GraphQL schema is automatically derived from this service structure and its resources.

We can write a simple ballerina-graphQL server like this,

import ballerina/graphql;
 
service graphql:Service /query on new graphql:Listener(8080) {
 
 resource function get name() returns string {
    return “Sam”;
 }
 
}

The above service can be mapped like this as well.

type Query {
 name: String
}

So we can send the GraphQL query below to look up the exposed name field in the root query object.

{
 name
}

We can run the above ballerina service using,

$ bal run your-file-name.bal. 

This will expose a GraphQL service at the endpoint “http://localhost:8080/query”. We can send query calls like this.

$ curl -X POST -H "Content-type: application/json" -d '{"query":"{name}"}'

And tada! we get a response like this.

{"data":{"name":"Sam"}}

What we did here is work with static data but this can be done with dynamic data as well. Okay, I think you might get a basic idea of the ballerina-graphql combination. Let’s meet again with some more examples and deeper concepts on ballerina-graphql. Bye!