What are GraphQL APIs?

APIs have become the dominant paradigm for apps to communicate with services. Developers sign up, cURL, try the APIs, and then embed them into their applications. And voila, the data they need to build amazing experiences appears when they need it.

For over a decade, REST APIs have been the gold standard for APIs. REST has become the predominant pattern (replacing SOAP/XML) because of its simplicity, and the availability of tooling around it. And with REST APIs, a new software spend category emerged—API Management, which encompasses security, scale, analytics, developer experiences and the monetization of APIs.

GraphQL APIs: A step-jump beyond REST APIs

A new category of API structure is now emerging—GraphQL APIs. GraphQL APIs take the best of REST (http/https-based URL style endpoints) and allow a query or mutation to be issued against it. Just that extra flexibility makes a step-jump in the developer and app experience compared to standard REST APIs.

Let’s take a look at a GraphQL query that an app developer might use when they are building an e-Commerce site, and the corresponding response (of course the actual application will not use the GraphQL tool shown in the following screen capture):

The developer requests customer details (name, order, and so on) after the user has logged in. The API responds with exactly the information that is requested. Equally important, the developer does not know (and frankly should not care) where the information is coming from. In this case, it happens to come from a REST API that contains the customer data, and a database that connects the order data. These disparate sources are queried using their respective protocols, and stitched together, and as a result, the developer gets a magical experience.

This experience is why GraphQL APIs are becoming popular – the ease of consumption from one API that stitches multiple backends together.

However, someone has to build that one API, which is where some of the hard problems occur and need to be solved. These problems include (and many many more):

• Variation in backend protocols and responses—REST, SOAP/XML, different flavors of SQL and NoSQL, and even GraphQL.
• Differences in access control and authorizations across the backends.
• Performance: what good is one API that can access a myriad of backends, if it is slow as molasses?
• Scalability
• Securing the APIs
• Change management across backend schema
• Preventing leaky abstractions
• Federating across the work of many teams

Building GraphQL APIs with IBM API Connect

There are many tools available for an API developer to build a GraphQL API. However, in most of these tools, the hard problems mentioned above need to be coded in, which may seem like a fun job, but can quickly get out of hand. For example, a classic problem in GraphQL is the N+1 problem—one call for a parent may result in N calls for the child data. Can these N+1 calls be executed as one call to the backend (if the parent data and the child data are all coming from the same database backend)? These and many more become unmanageable when the solution is “code” everything.

Since the acquisition of StepZen, in February 2023, IBM API Connect has GraphQL capabilities that allow for a different approach. We draw our inspiration from the success of declarative databases. Developers and users specify what they want, and the database executes the hard things (laying stuff out on disks, query optimization, transactional serializability etc.).

With API Connect's GraphQL development capabilities, we help developers build out their GraphQL API by creating composable building blocks, and then assembling the building blocks. Each building block encapsulates one or more backends (using declarative constructs like @dbquery, @rest and @graphql to encapsulate database, API, and GraphQL backends respectively). Stitching the building blocks is a simple matter of declaratively passing the data from one block, through a series of transformations, into a query of the second block. Once assembled, these building blocks are given to API Connect, and API Connect then serves up that API, while automatically scaling, optimizing and protecting the API.

One advantage of this building block approach is that what is needed to build an API is the same as what is needed to federate the API. Unlike other tools out there that treat federation differently than build out, in API Connect, it is a seamless experience.

And equally important, this all works seamlessly with the API management features of API Connect (and other API management tools) so that GraphQL APIs built in API Connect can be managed consistently with other APIs that you are managing.

Summary and next steps

IBM API Connect takes a declarative programming approach by using declarative building blocks without the need for custom code. App developers can iterate faster on their APIs by creating a unified GraphQL API layer for all their data.

Learn more about the Essentials plan in API Connect and see how you can start building GraphQL APIs in minutes.