What is GraphQL and how does it work?

GraphQL is a query language for APIs that enables clients to interact with a single endpoint to get the exact data they need—without chaining requests together. This approach reduces the number of round trips between the client and the server, which can improve performance.

In comparison to REST and SOAP, GraphQL provides wider access across a large number of schema objects and properties, making for a more flexible and powerful way to make digital resources available via web APIs. GraphQL also does not return data the client didn’t ask for, which improves efficiency by reducing the amount of data that is transferred. These benefits have led GraphQL to experience a significant surge in popularity in recent years.

Related: Download the Postman GraphQL Client

A brief history of GraphQL

In 2012, Facebook created GraphQL to improve data fetching across their services and to help developers implement the News Feed section for their iOS apps. Their goal was to create a system that would be easy to understand for developers, designers, and non-technical users alike. GraphQL was used internally at the time, but the company decided to make it open source in 2015.

How does GraphQL work?

Rather than designing individual API paths for each underlying resource, GraphQL gives you a single URL to query the data you desire as a consumer. Much like structured query language (SQL), and other database query languages, GraphQL provides a language for making requests of the data, while also describing the structure of the data being returned.

GraphQL API request example

Similar to other web API styles and protocols, you can make a request to a GraphQL API using the API’s URL:

• http://example.com/graphql

When using GraphQL, you can choose to either use HTTP GET or HTTP POST to send your query. If you are sending a query via the body of your HTTP POST method, it might look something like this:

{
 __type(name: “Book”) {
  name
 }
}

This query is designed to search the data but also define what the structure of the data should look like, instructing the API to return just the name of all entries named “book”:

{
"data": {
 "__type": {
  "name": "Book"
  }
 }
}

GraphQL gives API providers a standardized way to deploy an API on top of a database, and gives API consumers robust querying capabilities using common web infrastructure. GraphQL only uses what it needs from the HTTP protocol, while heavily investing in a standardized message format over leveraging what already existed within HTTP. Consumers can get up and running pulling the data they need in a consistent and scalable way. Using the web to make data and content accessible, GraphQL brings forward many of the database capabilities developers are used to on the backend to give them the ability to rapidly build web, mobile, single page, and other types of applications.

Advantages of GraphQL

Graphs instead of resources

GraphQL is all about seeing your data as a graph, and then querying that graph. It allows you to precisely define the schema of the data you are making available, then gives you a powerful query interface to navigate, traverse, and discover what you need. GraphQL gives you a strong framework to think deeply about each of the objects you are making available, then helps you define the relationships between these data objects, as well as additional iterations or variances of each object. You can better manage the data and how it is all related, while also getting help dealing with change across that data over time. GraphQL goes beyond just being a database, or a set of data resources, and empowers you to look at it all as a single entity that can be queried and traversed based upon how it is all connected.

APIs for web and mobile applications

GraphQL excels at delivering exactly the data that frontend developers of modern web and mobile applications need. GraphQL is an open source project developed at Facebook, as well as the popular single-page application platform React. Providing a powerful example of how APIs are being leveraged for the next generation of web and mobile interfaces, GraphQL APIs can significantly speed up the development of frontend applications by giving more control to the developer when it comes to querying a database for data and content. It gets out of the frontend developer’s way, giving them the ability to optimize each API request for a specific requirement of their multi-purpose applications. GraphQL provides an effective architectural style for rapidly delivering robust APIs, but also speeds up the development of the applications that will be putting these API to work.

A query language for APIs

Platforms like Facebook, GitHub, and Pinterest use GraphQL to help them not only make their massive amounts of data available to their consumers, but do it in a way that empowers frontend developers to be more agile and precise in how they deliver data and content to web and mobile applications. This provides a robust way to query data using a single HTTP URL, allowing developers to completely shape the structure of each API request and optimize the data that is returned. Developers can create, read, update, and delete data across large graphs of interconnected data that have all of the relationships defined and mapped out as a graph.

GraphQL APIs put the power and control in the hands of the API consumer—giving them exactly what they need, in the format they need it in. GraphQL uses the web as a transport but relies on its query language to negotiate what is being sent and received. Employing GraphQL, next-generation UI frameworks like React, Gatsby, and others assume modern application developers will be API-first, writing web, mobile, and single-page applications to GraphQL APIs. Ultimately, GraphQL provides a pretty powerful data view of the enterprise API landscape, giving API providers another powerful tool when it comes to making digital assets available via the web.

Selective data fetching

GraphQL reduces the risk of over-fetching and under-fetching data by allowing clients to send a single request and specify the exact data they want. This also helps improve performance by reducing the number of round trips between the client and server.

GraphQL with microservices

In a microservice-based architecture, applications are composed of many small services that can be deployed, provisioned, and scaled independently of one another. These services are connected to one another through APIs, and they are commonly used in conjunction with commercial platforms and business tools. GraphQL APIs facilitate communication between these microservices and commercial platforms by merging everything into one GraphQL schema.

Disadvantages of GraphQL

Complexity of a GraphQL query

GraphQL is a simple query language—not a replacement for server-side databases. When a query is made, the server accesses the database. This can lead to problems when a client requests data from too many nested fields at a time. In order to avoid inefficient requests, there must be maximum query depths, query complexity weighting, and mechanisms for avoiding recursion.

Caching in GraphQL

It is more complicated to implement a simple cache with GraphQL than with REST. In a REST API, resources are accessed with URLs, which makes resource-level caching possible. In contrast, every GraphQL query can be different—even those that operate on the same entity.

Rate limiting

Rate limiting is another challenge with GraphQL. In a REST API, you can specify the amount of requests in one day. However, it is difficult to enforce this type of limit with GraphQL.

HTTP code 200

Every response to a GraphQL API request has an HTTP status code of 200—even if there was an error. This makes issues harder to debug.

A steep learning curve

Learning GraphQL can be a challenge, especially for developers who are primarily familiar with RESTful APIs.

Tool maturity

Despite the growing popularity of GraphQL, its tooling ecosystem is still less robust than that of REST. It might therefore be challenging to find comprehensive resources and community support for certain use cases, as some development tools, frameworks, and libraries may have limited GraphQL support or documentation.

The future of GraphQL

Hear from industry experts about their thoughts and predictions around GraphQL, and watch a companion GraphQL panel-discussion video here.

More resources

Make sure to explore these resources for further insights into Postman and GraphQL:

• Making your first GraphQL query
• Using GraphQL Requests
• Initiating your journey with the latest GraphQL Client
• Unveiling the new GraphQL client by Postman
• How to choose between REST vs. GraphQL vs. gRPC vs. SOAP
• GraphQL vs. REST