GraphQL APIs are Most Definitely Not RESTful. So, What are They Then?

Sometime in Q4 of 2019, ProgrammableWeb will be launching an overhaul of the data model that drives our world-famous API directory. Now, more than two years in the making, this update to the foundation of our site will be one of the most ambitious technical undertakings in ProgrammableWeb’s history. Not only does the data model take into account some of the most recent trends in the API economy (trends that are, ahem, stressful to our current data model), it will set us up for three killer features; an incredible power-search, an API of our own (the so-called API of APIs), and along with that API, the ability for API management systems to update our directory automatically (as opposed to swivel-chair Integration, cut n’ paste style).

But as we hammered through the many challenges, one issue we struggled with and talked to experts about, had to do with how to classify the emerging group of GraphQL APIs within our directory. GraphQL APIs are most definitely not RESTful APIs. They bear some resemblances to RESTful APIs in that they rely on the protocol of the World Wide Web ( HTTP) for making API calls (Reality Check: HTTP support is not a requirement for RESTful APIs, even though it seems that way). Like many RESTful APIs, they even use JSON for Payload formatting. But, their architectural style is most definitely not RESTful.

This led us to the next question. If REST is not the architectural style of a GraphQL-based API, then what is? Originally, we were inclined to add a new architectural style to our taxonomy called GraphQL. In fact, if you’re reading this article prior to our launch, GraphQL literally is one of the architectural styles you can choose from when inputting a new API into our directory. But to continue doing this would have set an ugly precedent. The idea behind architectural styles is that they should work for multiple API technologies (which would not be the case if GraphQL were an architectural style). For example, whereas some RESTful APIs use HTTP as their intermediating protocol, others might use CoAP (perhaps for use-cases involving the Internet of Things). Likewise, the RPC and Streaming architectural styles are both supported by multiple API technologies. For example, Websockets and Webhooks are two technologies that support the Streaming architectural style of APIs. Throwing a little twist into our deliberations, Webhooks are also RESTful (just in the reverse direction of typical API calls).

After much deliberation, we decided that GraphQL was more of a payload formatting issue and not an architectural style unto itself. Instead, GraphQL falls under the RPC architectural style along with other APIs powered by SOAP, XML-RPC (SOAP's ancestral predecessor), and the emergent GRPC. You may disagree and we are open to debate on this issue. However, GraphQL APIs exhibit a pattern that is unmistakably RPC-like.

With RESTful APIs, the procedural part of the API call is invoked through one of the intermediating protocol’s built-in verbs (eg: the PUT, GET, POST or PATCH verbs of HTTP). In the case of RESTful APIs, the developer may have to familiarize himself or herself with the API's resources and how to best apply the right verb at the right time to those resources. 

In contrast, with RPC-styled APIs such as SOAP-based Web services or XML-RPC, the procedural part of the API call is literally a procedure that lives on the Remote Server. Ergo, a " Remote Procedure Call” or “RPC." Not only must the developer call the remote procedure by name, but the developer also has the added burden of keeping track of all the procedures that are available from each API. For example, with a RESTful HTTP-based API, there may be a single Resource called “Customer” where the developer just needs to apply the standard HTTP verbs POST or GET to add or retrieve customer information, respectively speaking. 

One of the biggest advantages of this approach is that from one RESTful Web API to the next, the developer need only be familiar with HTTP’s built-in verbs to invoke a procedure. With an RPC-styled API, the equivalent procedures on the remote server might be named “AddCustomer” and “RetrieveCustomer”. Not only are there two completely separate procedures for the developer to keep track of, similar procedures in other RPC-style APIs may have completely different names (“NewCustomer” and “CustomerLookup”). It starts to get messy. 

On the positive side, GraphQL relies exclusively on the Web’s (HTTP) POST verb for all API calls. Yes, all. Beyond that, however, things start to look very RPC like. Although this is an oversimplification, GraphQL APIs involve something very procedure-like (it even includes business logic, just like any procedure would) called a Resolver (for more on the nuts and bolts of GraphQL see Guide to GraphQL: Understanding, Building and Using GraphQL APIs). GraphQL Resolvers live on the remote server and application developers must essentially invoke them by name in order to get the desired results. To us here at ProgrammableWeb, this subtle distinction is enough to qualify GraphQL APIs as RPC-styled APIs and therefore, moving forward, they will be categorized as such in ProgrammableWeb’s API directory. 

Most importantly, our decision to classify GraphQL APIs under the RPC architectural style moving forward will in no way impede the searchability of our directory. Once our new data model is in place, our next move will be to enable a power search feature that makes it possible to build sophisticated queries (ie: show me all GraphQL APIs) involving most of the important fields we use to classify APIs. It’s a feature that we’ve wanted to offer our audience for a long time and now that our new data model is nearly in place (or, it may already be in place by the time you read this), it shouldn’t take too long to get our power search up and running.

Be sure to read the next API Design article: US Court of Appeals Irreparably Damages API Economy