What is GraphQL?

If you’ve been working with APIs for the past few years, then you’ve likely heard of GraphQL. But, what is it exactly? A language? An API model? Do I use it to build a server or a client? When should I use it and what benefits does it bring?

In this article, we’ll look at what GraphQL is and the benefits it provides. We’ll also introduce the Kong API Gateway and how it works with GraphQL clients and APIs.

So, what is GraphQL?

GraphQL is both an API query language and a runtime engine for responding to those queries.

Applications can call GraphQL services using GraphQL queries. These queries will return the exact data elements the client requests and nothing more or less. This saves multiple API calls, network bandwidth, and post-processing. For data-centric APIs and APIs sitting right at the edge, close to consuming devices like mobile phones and tablets, it’s an incredibly efficient solution.

GraphQL was developed by Facebook in 2012 and later open sourced in 2015. With growing adoption, the popularity of GraphQL is rising. This is because it’s an excellent choice for organizations looking to make their dispersed data easily available through APIs. Not surprisingly, big names like Github, PayPal, Shopify, Netflix, and Facebook use GraphQL.

Although REST remains the predominant method of accessing APIs, GraphQL doesn’t replace it. REST is an architectural framework for creating APIs, while GraphQL is a run-time engine and a query language. 

As a run-time engine, GraphQL is implemented as a server. The server exposes data as GraphQL API services that applications can query. These services  are usually accessible via URLs. The client applications may range from regular web pages to mobile apps to traditional desktop software. 

When a query runs, the GraphQL API pulls the requested data from multiple sources, such as REST APIs, databases, or even microservices. The server hides the underlying data sources and exposes the data through the API. Unlike traditional query languages that work against only single data sources, GraphQL queries can thus access data from different sources—all in a single API call.

How GraphQL works

GraphQL was designed to address two requirements. The first one is that data returned by a source needs to fit exactly what the client is looking for. The second is that the design of an API or data source shouldn’t dictate the way the client consumes the data. 

To satisfy these requirements, a GraphQL service defines a schema.

Schemas, fields, types, and resolvers

A GraphQL schema describes the data clients can request from the GraphQL API. It encompasses all the possible data that the client may want the query to return. Ideally, this schema will be represented in the form of a Schema Definition Language (SDL) to make it more readable.

The schema comprises object types that define what kind of objects the queries will be able to access and the fields within those objects. For example, the snippet below shows the schema of a GraphQL query.

type query {
    students {

You can see that the schema has two fields, teacher and students

If an application wanted to access the names of the students and their teachers from a  traditional REST API, then it would run a query against the API URL, and the API might return the teacher name, number of students in the class, the class subject, the student names, and student ages. In other words, the client would have more data than it needed. However, if this schema was defined at the GraphQL service and the application ran the query, then the application would get only what it wanted: the students’ and their teacher’s names. The output may look something like this:

   "data": {
     "teacher”: "Joe Bloggs",
     "students": [
         "name": "Jane Doe"
         "name": "Joe Smith"

Each field within the object type will have a type of its own. A field’s type can be another object type or a scalar type like String, ID, Boolean, Int, or Float. For example, the schema for the class object can be defined like this:

type class {
  teacher: String
  student: [StudentName]

type StudentName{
  name: String

Each field in the schema will then be attached to a resolver. A resolver is a function that fetches the data for that field for GraphQL queries. The GraphQL query engine compares every query against the schema during runtime to validate the query. If the query is valid, then the query engine runs each field’s resolver to fetch the data for that field. 

GraphQL operations

As we keep talking about GraphQL queries reading data, it may seem that this is the only allowable operation type. This is not the case. A GraphQL client can request one of two types of operations: a query or a mutation.

A GraphQL query is similar to a REST API’s GET method. This is what we have been talking about so far—this operation accesses data. A mutation is a request to add or modify data. This is similar to the REST API’s POST, PUT, PATCH, or DELETE methods.

GraphQL subscriptions

Now, instead of a client sending queries to a GraphQL API, sometimes the server may need to push data to the client in real time. This is what GraphQL subscriptions do. Subscriptions allow a particular event at the server end (for example, a deletion or update) to trigger a notification to the subscribing clients. Clients subscribe to these events using subscription queries.

Subscriptions are similar to queries because they specify a schema of fields to be returned. However, instead of an immediate, query-response model, the client’s subscription query specifies what events it’s interested in and the data to be sent to it every time the event happens. 

For subscription, the client opens a long-lived bi-directional communication path with the server—typically through WebSocket—and sends the subscription query. This is different from the HTTP connection used by GraphQL queries or mutation requests which closes after the server sends its response.

GraphQL benefits

No over-fetching or under-fetching 

GraphQL ensures that only the data you’ve requested is presented to you. If you compare GraphQL with REST queries, you’ll notice that receiving custom datasets is quite difficult with REST. When REST fetches data from a single endpoint, then there may be more data than you need (over-fetching). 

On the other hand, when the requested data isn’t available from a single source, then you have to make multiple REST API calls, which translates to under-fetching from a single source. 

GraphQL solves these issues by defining a schema that dictates exactly what data elements a query can request and receive. 

Low network footprint

Getting a specific set of data each time also ensures GraphQL queries work with significantly smaller payloads than those received with over-fetching. 

Also, as GraphQL queries don’t have to send multiple requests to multiple resources, there’s less network traffic. This is beneficial for distributed applications accessing one another over geographically separate networks. 

HTTP/HTTPS protocols

GraphQL queries can use HTTP/HTTPS protocols for accessing the APIs. This means you don’t have to cater to new communication methods when designing your applications.  

Evolving APIs

While GraphQL services can be versioned just like REST APIs, it provides you with the tools for the continuous evolution of the schema. You can add new types and fields to the schema without breaking existing queries. This is because the GraphQL service will only return the data elements requested. If you need to return new fields and objects, then you create new queries.

Strongly-typed schema

GraphQL schemas and their object types are defined in a hierarchical and declarative manner. This helps developers understand the relationship between data elements (such as, the “Graph”) and fine-tune the query structure.

Also, the schemas and objects are strongly typed. The GraphQL runtime engine ensures the query is both syntactically accurate and its types match the requested schema’s fields and object types. 

If there’s a mismatch, then the service returns an error message. Having strongly typed and well-defined schemas means query behaviors are more predictable, and errors are easily detectable.

Rich set of tools

GraphQL boasts a vibrant ecosystem of development and testing tools. Some of these tools are open source, making them much easier to develop. Popular GraphQL tools include Apollo, Graphback, GraphiQL, GraphQL Playground, and GraphQL Explorer.

Introducing Kong API Gateway

Depending on how the resolver functions for each field in the schema are implemented, a single GraphQL query can generate a flurry of traffic to backend systems. Therefore, the rate-limiting or caching features used for traditional REST APIs don’t help when facing large-scale traffic. This is where the Kong API Gateway can help.

Kong is the world’s most popular API Gateway built for hybrid and multi-cloud environments and optimized for distributed microservices-based applications. It offers unparalleled performance and scalability for APIs. 

Kong supports GraphQL natively and can protect and manage existing GraphQL endpoints and route queries to them. Also, Kong has a rich set of plugins, including those for GraphQL query proxy caching, GraphQL rate limiting, and even transforming a GraphQL upstream into a standard REST API.

Contact us today to schedule a personalized demo.