How GraphQL Can Improve IBM i APIs
March 9, 2020 Alex Woodie
IBM i shops are embracing APIs as a method for accessing data and programs, just like the wider IT world. As RESTful Web services overtook SOAP-based ones in popularity, IBM i shops moved with them. Now a new approach to Web services, dubbed GraphQL, is gaining traction in the wider IT world, and leading IBM i developers are right there again.
GraphQL, if you’re not familiar, is a relatively new language and runtime for exposing and consuming APIs. The software, which was originally developed in 2015 by Facebook to streamline delivery of content in complex environments, essentially provides an abstraction layer that gives developers more freedom to call the exact services they need to fulfill requests compared to older REST and SOAP methods.
Web services based on REST and SOAP (and microservices as well) have had a big impact on how developers create Web and mobile apps. However, these older approaches rely on procedural code, and they are, therefore, somewhat rigid in how developers can use them (at least compared to GraphQL). It’s not uncommon for an application to call dozens of REST or SOAP services to fulfill a user request, with individual API calls going to multiple databases, backends, and other servers.
At first, developers had no problem developing all and maintaining all those point-to-point REST or SOAP services. However, as the number of Web services increased, sometimes reaching into the hundreds of individual services, it has become a burden on the developer to maintain them. Requiring many APIs to feed data for a single request also slows performance, particularly for mobile phones in bandwidth-constrained environments.
The new GraphQL approach is designed to simultaneously address both of these issues – the burden on the developer for creating and maintaining hundreds of REST or SOAP microservices, and the performance degradation from fulfilling complex API requests in Web and mobile environments.
Query Your APIs
GraphQL exposes a query language that basically allows users to “query their API,” as the GraphQL website states. “A GraphQL service is created by defining types and fields on those types, then providing functions for each field on each type,” the website says.
Once the user has defined their data in GraphQL, then they can expose that data to GraphQL queries. Running on a server, the GraphQL runtime essentially acts as a broker that intelligently federates incoming API requests to the downstream systems that fulfill those requests. It behaves in some ways like a graph database, in that it’s able to establish and maintain connections among different back-end entities, which could include relational databases, NoSQL databases, S3 cloud data stores, file systems, Hadoop, and search engines like Elasticsearch.
Geoff Schmidt, the co-founder and CEO of leading GraphQL software company Apollo, described it this way in a 2018 article in Datanami: “This kind of sits on top of all your existing services and super-imposes a graph on all those cloud assets and resources so application developers can freely query that without the friction of having to create a new REST endpoint for every new use case.”
GraphQL delivers data from multiple backends in a single HTTP request.
Essentially, GraphQL eliminates the need for a developer to hand-code individual REST requests into their applications (although it’s also compatible with REST and SOAP and will work with them too). Instead of working with REST and SOAP APIs, developers simply select what data they want, and GraphQL handles the rest. Schmidt compared this approach to the difference between shopping in a grocery store that sells individual ingredients (the GraphQL approach) versus a store that only sells meal kits (the REST and SOAP-based approach).
In addition to simplifying life for developers, it also cuts down on the amount of data that’s returned. A single REST call may return dozens of pieces of information. But if your application only requires one or two of them, there was no way in procedural REST (or SOAP) to prevent all of those requests from returning. With GraphQL, the developer can be much more targeted in her approach to calling services and the payload (and bandwidth consumption) will be much smaller as a result.
GraphQL On IBM i
Facebook released GraphQL as an open source standard in 2017 and since then a community has begun to grow around it. In addition to the GraphQL package from Apollo, there are GraphQL libraries for most popular development languages, including Node.js, Java, PHP, JavaScript, Python, Ruby, etc.
GraphQL has trickled into the IBM i world too. Power Champion Liam Allan has started to play around with the technology and has found it favorable to using REST for getting data out of IBM i servers and its relational database.
“REST APIs work and everybody knows them,” Allan said in a recent webinar on GraphQL hosted by Seiden Group, where he works as a consultant. “The problem with REST APIs is defining the relationship between them. Other than documentation, there’s no real relationship between them . . . . And there’s a lot of places where documentation for APIs doesn’t exist.”
GraphQL implements a new API architecture. (Image source: TutorialsPoint)
The maintenance burden of REST APIs has also come to Allan’s attention. “I can tell you from experience, you can just build and build and build REST APIs and they can grow very quickly,” he says in the webinar. “That indicates they’re harder to maintain, let alone document. They might be everchanging, and it can become a real pain in the backside.”
The maintenance burden, plus REST’s tendency to “over fetch” data, has driven Allan toward GraphQL, which he says can simplify this work. The young IBM i developer says he works primarily with the open source express-graphsql package that’s supported by the GraphQL project on GitHub. Allan has also used the .NET GraphQL server for a mobile application that uses Apollo.
“What GraphQL can do is fix a lot of these issues. It can take what’s great about RESTful APIs and make it easier to develop and maintain long term,” he says. “Because of the way GraphQL works — and there’s only one schema — you don’t need to actually build multiple RESTful APIs. There is one single API and the front-end can request whatever information they want.”
There’s been a lot said about GraphQL since it burst onto the scene in 2018, and not all of it is good. For starters, it could be overkill for smaller projects. Plus, it doesn’t necessarily improve performance out of the box, and requires its own optimization (which Apollo’s implementation can provide). Check out Honest Engineering’s take on GraphQL to hear some of the criticisms of the nascent technology.
But for larger IBM i shops that are developing more elaborate Web and mobile apps that touch multiple backends, it could be worth the effort. Allan certainly is a backer, and that’s saying something.
“I love GraphQL. It’s fantastic for big data sets,” Allan says (specifically, it’s good for normalized data, but not so good on denormalized data). “If you build the API correctly, it can have built-in paging for data sets. It can have built-in limits and offsets, built-in where clauses. It can handle a lot of the sort of paging that you’d have to write manually in your pages. That’s a key point: It can do a lot of the work for you.”
The key advantage of GraphQL, Allan says, is that you define the data source once, and then you never have to do it again, due to the way GraphQL manages relationships. “It’s much easier for clients, as in mobile apps or Web pages, because again there’s only one API and the front-end can just specify what data you actually need,” he says. “That’s the key point.”
