API Design: GraphQL vs. REST

Introduction

API design is crucial because it gives structure to how applications interact with each other. Given cross-functional teams and applications, development time is drastically reduced when there is a clear and intuitive way to access needed data. API development often follows two popular approaches: REST and GraphQL.

Basics of a REST API

Traditionally, APIs have been built following REST. REST is an architectural principle built on two key ideas: the separation of client and server, and stateless information transfer. In a REST API, the client has all the information it needs to make server requests. It is also platform and language agnostic. This makes the client portable and flexible. A RESTful API uses standard HTTP requests (GET, POST, PUT, DELETE) to request information from a server. Because of this, REST APIs follow a uniform format and are easily understood across applications and services.

Disadvantages of REST APIs

The uniformity and structure of REST does create some inflexibility. Each endpoint in a REST API corresponds to a single HTTP request for a particular resource. This makes interacting with specific pieces of data easy. However, when data is needed across multiple API endpoints, retrieval becomes cumbersome and resource-intensive. Furthermore, as the complexity of the data grows, REST APIs can become convoluted.

Imagine a simple REST API for a content website. The endpoints are simple initially, but the complexity grows fast.

Now we can see endpoints becoming exceedingly long and unintuitive. With REST, these kinds of endpoints occur more frequently. As the application grows, the API can become very complicated.

Another downside to a REST API is over-fetching and under-fetching of data. The server can send more or less data than needed, creating extra load on the application. Solving this issue by creating very specific APIs leads to more endpoints in the long run, and maintainability becomes difficult.

When documenting APIs using a tool like Swagger, a REST API can be challenging since endpoints do not have to be strongly typed. It is not easy to specify the data and integrity of a API endpoint that does not have strict requirements. Furthermore, API versioning can prove tough. In a large application, different environments could run different versions of the API that return different sets of data. More API versions equate to more endpoints, and more code to maintain in the long term.

How is a GraphQL API different than REST?

GraphQL has become popular in recent years as another way to construct APIs. So, what is GraphQL? GraphQL is a query language that a developer uses to write a query to interact with the API. Even a complicated query completes itself in only *one *HTTP request. This single query contains the sought after data requirements, and the API sends back a JSON response that fulfills ALL the specifications.

A GraphQL schema defines the client-server data contract and what is possible to query. Because of this defined schema, teams can work relatively independently of each other. Changes to this schema, though infrequent, are generally easier than updating or adding endpoints in a REST API. An important note is that in GraphQL, the query will be what is changing, while the GraphQL schema that defines the data often remains the same.

Our same complex endpoint in a REST API would instead have a GraphQL query like the following:

A single query gives only the necessary data. If you want the query to return additional information, simply append it to the query. Thus, additional development cycles are not spent spinning up custom API endpoints. This causes a GraphQL query to typically be *faster *than REST, because the specificity of the query means you get back only what you need.

Furthermore, GraphQL is strongly typed, leading to consistent and accurate documentation. It is also schema-extending. Therefore, if business requirements change, modifying the schema does not break dependent code. GraphQL also deprecates fields that are no longer used, making versioning trivial.

Using GraphQL vs REST does have a few key downsides.

Disadvantages of GraphQL APIs

• Non-Existent Caching: GraphQL does not have support for browser and mobile caching, while something like REST does utilize native HTTP caching mechanisms.
• Monitoring and Error Reporting: GraphQL services always return a 200 OK response. This makes it difficult to handle error scenarios and makes the monitoring process cumbersome.
• Exposed Schema and Resource Attacks: Unlike RESTful services, GraphQL services mandate that the client knows about the data schema to query.
• Security—Authentication and Authorization: There is still no native solution to integrate authentication and authorization.

Can your business benefit from GraphQL? See our checklist to help make that determination.

REST vs GraphQL: Will GraphQL Replace REST APIs?

When deciding how to design an API, consider the kinds of data the application will need to access. Will the requirements remain fairly stable over time and consist of simple resource retrieval? If so, a REST API provides uniformity and a modular structure that allows for easy data interaction. On the contrary, GraphQL is a query language that gives you the flexibility to work with a changing list of business requirements. GraphQL is also easily scalable for more complex data sets as a GraphQL query uses a single request model.

While GraphQL APIs have surged in popularity and have many benefits, REST APIs have greater market traction due to their longevity, familiarity, and seamless fit with a microservice architecture. GraphQL is still considered a more “immature” technology that will be refined over time, and will likely not replace REST altogether.