When comparing API design styles, it’s essential to place the utmost importance on the needs of consumers. According to the Smartbear 2019 State of API report, usability, performance, and documentation are the most critical factors for consumers using an API. Thus, the ideal design style should excel in these three areas. In this article, we compare two design rivals — GraphQL and REST — across these three categories, drawing insight from everyday examples.

Usability

When it comes to usability, REST and GraphQL are two entirely different beasts, especially with regards to predictability. With REST, for example, the behavior of the API wildly varies depending on the URI and HTTP method chosen, making it difficult for consumers to know what to expect with a new endpoint. On the other hand, GraphQL is predicated on explicit operations (queries and mutations) that deliver predictable outcomes.

“With GraphQL, because you’re explicitly defining in the payload what you’re doing — so you’re saying I’m doing a query or I’m doing a mutation — it’s extremely clear to a consumer what’s happening with the API.”

Versioning is another aspect of usability that differs between the two design styles. REST has no clear rules for versioning, meaning that each provider uses their own approach (despite author Roy Fielding’s belief that APIs should not be versioned whatsoever). On the contrary, GraphQL has a straightforward, established approach to versioning: don’t version.

In both aspects — predictability, and versioning — GraphQL’s simplicity greatly contributes to usability. On the other hand, REST’s flexibility is mostly a neutral characteristic, which can positively or negatively impact usability depending on the individual API’s design.

Performance

To compare the differences in performance between REST and GraphQL, consider a user interface that retrieves information about the countries you select on a world map by means of an API. With a REST API, selecting three countries would result in three API calls — one for each country. On the other hand, just a single request would be needed to a GraphQL API to access the same information.

“Often, GraphQL is presented as a revolutionary new way to think about APIs. Instead of working with rigid server-defined endpoints, you can send queries to get exactly the data you’re looking for in one request.” – Sashko Stubailo, Apollo GraphQL

However, if a content delivery network, web cache, or reverse proxy was sitting in front of the REST API, it could likely return cached responses for all three calls faster than the GraphQL API could return its single response. This is because a GraphQL call has to go back to the source of the information to retrieve exactly what the consumer asks for. Indeed, there are some caching options for GraphQL, but not at the HTTP level (as in the case of REST).

“Caching is built into the HTTP specification which RESTful APIs are able to leverage. GET vs POST semantics related to caching are well defined, enabling browser caches, intermediate proxies, and server frameworks to follow.” –Derric Gilling, Moesif

Performance is a category where the comparison of REST and GraphQL is much less clear-cut. Although GraphQL wins in the number of API calls needed for an average application, REST wins in the extensiveness of its caching options.

Documentation

The maturity of REST has resulted in a plethora of options for automated documentation. From OpenAPI to API Blueprint, and everything in between, there is a wide range of specification and documentation standards, all displaying information in slightly different ways. On the other hand, almost all public GraphQL APIs document using a single tool: GraphiQL.

Unfortunately, automated documentation for both design styles is still insufficient. While it may offer necessary information about endpoints and objects, it rarely handles subjects such as authentication, rate limiting, or even financial implications. In any case, REST’s maturity is a double-edged sword, since rich tooling offers functional variety at the expense of a consistent experience; GraphQL, of course, faces the opposite problem.

A Common Theme

Despite a close rivalry between the two design styles, both GraphQL and REST succeed in addressing the three most important traits of an API: usability, performance, and documentation. In terms of usability and documentation, a common theme is that GraphQL offers simplicity and predictability, while REST boasts greater flexibility. (Ironically, this is the very opposite of how endpoint behavior is characterized in each of the two styles.) With regards to the performance of the two styles — a contentious topic — it seems there is still something to be said for REST and its enthusiastic use of HTTP: caching.

Choosing Between GraphQL and REST

Ultimately, an API’s ability to excel in these three areas depends less on whether it is designed with REST or GraphQL (or any other design style), and more on how it is designed. With that said, it’s worth bearing in mind that each design style has its own quirks and features, which might lend themselves well to an API’s specific design considerations

For example, a standout feature of GraphQL is its advanced querying functionality. With REST, basic querying is no problem, but as the number and complexity of query parameters grow, messiness can arise. As a result, APIs warranting extensive querying might be better served by GraphQL.

On the other hand, REST has a significantly easier take on file uploads. Since it makes the most of HTTP, smaller files can be uploaded directly from a local machine or URL. On the other hand, GraphQL requires a separate upload service for even the smallest files. Thus, the need to quickly and easily upload files such as images might make REST the preferred choice.

In conclusion, the skillful API designer should acknowledge how developers will use an API. Not only will this inform which design style best suits the API’s requirements, but it will also result in an excellent API regardless of which design style is chosen.