Published: 8 December 2023
Contributors: Chrystal R. China, Michael Goodwin
GraphQL is an open-source query language and server-side runtime that specifies how clients should interact with application programming interfaces (APIs).
Using an intuitive syntax that lets users make API requests in a single line or a few lines (instead of accessing complex endpoints with lots of parameters), GraphQL technologies make it easier to generate and respond to API queries. GraphQL represents an upgrade from traditional RESTful architectures.
In the early 2010s, Facebook was experiencing massive growth and transformation. But a growing user base and increasingly complex mobile app environment rendered its existing RESTful approach—which required multiple round trips to different endpoints to fetch all necessary query data—unsustainable.
Representational state transfer (REST) and RESTful APIs were ill-equipped to handle complex, data-driven user interfaces, and frequently encountered latency issues and data inefficiencies, especially for mobile users with limited or expensive data plans.
In response to these challenges, Facebook engineers developed GraphQL (along with single-page application platform React), releasing it as an open source solution in 2015. Ultimately, Facebook moved the service to the GraphQL Foundation, which comprises members companies like AWS, Gatsby, Intuit and IBM, in 2018.
Learn how both APM and ARM can enable faster decisions and resource application.
Register for the guide on observability
A GraphQL architecture’s declarative data-fetching features revolve around several key components and processes, each playing a unique role in data handling and processing.
They include:
GraphQL relies on a strong type system where all data types are recorded in the GraphQL schema definition language (SDL). Typed schemas dictate the types of data that can be queried in the API, and the relationships between the types and the operations available to the user. In other words, they define the capabilities of the API and the shape of the data clients can interact with.
Each field in a schema is backed by a resolver that populates data and determines the response to a set of fields. Resolvers—which can retrieve data from a database, a cloud service or virtually any other source—provide instructions for turning a GraphQL operation (for example, a query, mutation or subscription) into data.
When a query field starts, the system generates a call to the corresponding resolver to produce the next value. If a field produces a scalar value (for example, a string or number), the execution completes. If a field produces an object value, the query contains more fields for that object. This process continues until only scalar fields are left.
Resolvers also facilitate data formatting and help the system stitch together information from various data sources.
A data query is the request made by the client to the GraphQL server; it specifies what data the client wants to fetch. When a query comes in, GraphQL validates it against the schema definitions and—assuming the query is valid—runs it. The structure of a query typically mirrors the structure of the response data, making data requirements explicit and predictable.
Mutations are GraphQL operations that create, update or delete data on the server. They are analogous to the POST, PUT, PATCH and DELETE operations in RESTful APIs.
Similar to how a queries work, GraphQL mutations are validated against the schema and its definitions. Once the mutation is validated and started, the server returns a JSON response.
Though GraphQL APIs have emerged as a more efficient and flexible alternative, REST and RESTful were long the standard for API architectures. REST API is a structured architectural style for networked hypermedia applications, designed to use a cacheable, stateless, client/server communication protocol (usually HTTP).
Both GraphQL and REST enable clients to communicate with servers and request data, but there are key differences that explain the proliferation of GraphQL systems.
REST APIs are designed around resources (for example, any type of object, data or service accessible to the client) and work by having different endpoints (URLs) for each resource. They use a fixed data structure to determine the shape and size of resources they provide to clients.
When the client requests a resource, the server sends all the data associated with that resource. If a client only needs a subset of the data, it still receives all the data (over-fetching); if the client needs data that spans multiple resources, it will often must make multiple API calls due to inadequate data retrieval from the initial request (under-fetching).
GraphQL, however, uses a single endpoint that provides a complete and understandable description of the data. GraphQL queries can access resource properties and follow references between resources, so the client can get all the data it needs from a single request to the GraphQL server and avoid over-fetching and under-fetching issues.
In a REST architecture, changing the structure of the data often requires teams to version the API to prevent system errors and service disruptions for the user.
This means developers must create a new endpoint every time they change the structure, resulting in multiple API versions and complicating the maintenance process.
GraphQL eliminates the need for versioning because clients can specify their requirements in the query. If new fields are added to the server, clients that don't need those fields won't be affected. Conversely, if fields are deprecated, clients can continue to request them until they update their queries.
REST APIs use HTTP status codes to indicate the status/success of a request. Each status code has a specific meaning.
A successful request returns a 200 status code, while a client error might return a 400 status code and a server error might return a 500 status code.
GraphQL handles errors differently. Every request, regardless of whether it resulted in an error, returns a 200 OK status code. The errors are not communicated by using HTTP status codes; rather, the system communicates errors in the response body along with the data.
This approach requires clients to parse the response body to determine whether the request was successful, which can make debugging GraphQL APIs a bit challenging.
REST doesn't have built-in support for real-time updates. If a web or mobile application needs real-time functions with a REST API, developers must usually implement techniques like long-polling (where the client repeatedly polls the server for new data), server-sent events and WebSockets, which can add complexity to the application.
However, graphQL includes built-in support for real-time updates by using subscriptions. Subscriptions maintain a steady connection to the server, allowing the server to push updates to the client whenever specific events happen and enabling clients to stay on top of relevant API data.
The REST ecosystem is well established with a wide range of tools, libraries and frameworks available to developers. However, working with REST APIs often requires teams to navigate several endpoints and understand the unique conventions/patterns of each API.
GraphQL is relatively new, but the GraphQL ecosystem has grown tremendously since its introduction, with various tools and libraries available for both front end and backend service development.
Tools like GraphiQL, Apollo Studio and GraphQL Playground provide powerful in-browser integrated development environments (IDEs) for exploring and testing GraphQL APIs. Furthermore, GraphQL has strong support for code generation, which can simplify client-side development.
REST APIs rely on HTTP caching mechanisms like ETags and last-modified headers. While effective, caching strategies can be complex to implement and might not consistently optimize performance for all use cases.
GraphQL APIs can be more challenging to cache due to the dynamic nature of the queries. However, the use of persisted queries, response caching and server-side caching can mitigate these challenges and provide efficient caching strategies for GraphQL architectures.
Since GraphQL’s transition to the GraphQL Foundation, developers have created implementations for various programming languages, including JavaScript, Python, Ruby and PHP, among others. And GraphQL APIs have been adopted by myriad businesses, like Github, Pinterest, PayPal, Shopify, Airbnb and more, enabling more clients to streamline data specification, reduce excessive or inadequate network data transmission, and improve overall data-fetching capabilities.1
What’s more, enterprises and developers are pushing for open federation of GraphQL architectures. In its current iteration, GraphQL federation takes separate GraphQL services and aggregates them into a single GraphQL API, which serves as the entry point to all underlying backend data and facilitates single-request data fetching. However, unfortunately federation implementation is exclusive to a single vendor.
As a response, IBM is advocating for democratized federation, which facilitates data aggregation from both GraphQL APIs and non-GraphQL APIs instead of GraphQL-exclusive aggregation.2
IBM API Connect is a full lifecycle API management solution that uses an intuitive experience to help consistently create, manage, secure, socialize and monetize APIs, helping power digital transformation on premises and across clouds.
IBM API Connect makes it easy to build and deploy a production-level GraphQL API in minutes. Simply provide the connection details of your data source and a secure and optimized GraphQL API will be generated instantly.
Learn about the two different approaches these frameworks take for building APIs and the strengths and weaknesses of each.
Read the 2023 Gartner Magic Quadrant for API Management to find out why IBM continues to be recognized as a leader in API Management.
Explore the IBM API Connect toolkit.
Maximize API value to drive digital business with a comprehensive API management solution.
IBM named a Leader in the 2023 Gartner Report: Critical Capabilities for API Management.
These tutorials provide hands-on instructions that help developers learn how to use the technologies in their projects.
Footnotes
1 IBM acquires GraphQL startup StepZen to step up its game in API Management (link resides outside ibm.com), TechCrunch, 8 February 2023
2 Why GraphQL Needs an Open Federation Approach (link resides outside ibm.com), The New Stack, 16 November 2023