API Design: GraphQL vs. REST

Blog

February 7, 2020

TABLE OF CONTENTS

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.

Authored By

Amogh Sharma

Engineering Consultant

Sergio Villareal

Engineering Manager

RECOMMENDED CONTENT

HMG Strategy 2020: Executive Leadership Insights from Levvel CEO Chris Hart

Blog

KubeCon 2019 Retrospective: Why Kubernetes?

Blog

Everything You Need to Know About the California Consumer Privacy Act (CCPA) and How to Be Compliant

Blog

Meet our Experts

Amogh Sharma
Engineering Consultant

Amogh is an engineering consultant with experience in full-stack development and building enterprise scale web applications. He primarily works with Typescript on the front end with ReactJS, and on the backend with NodeJS. He has experience working for clients ranging from mid-sized insurance and fintech companies, to small startups.

Sergio Villareal
Engineering Manager

Sergio Villarreal has more than 15 years of experience in software development and technology consulting in addition to expertise in desktop, web, mobile, and cloud development end-to-end solutions. Some of the industries he's worked in are banking, oil & gas, and energy, among others. Since 2015, Sergio has focused on cloud architecture with an interest in ML and AI. Outside of work, he enjoys exploring nature with his wife and little boy.

Related Content

HMG Strategy 2020: Executive Leadership Insights from Levvel CEO Chris Hart

Levvel CEO Chris Hart spoke at HMG Strategy's CIO Executive Leadership Summit event. In this video series, Hart talks about effective collaboration, communication, and culture in the c-suite, as well as how technology sharpens the competitive edge.

Blog

Apr 30

KubeCon 2019 Retrospective: Why Kubernetes?

At the end of lunch with a mentee, I used the items on our table to express the fundamental concepts of Kubernetes. Sometime after explaining the purpose of the Kubernetes scheduler, she asked a question I spent the next several weeks thinking about.

Blog

Apr 01

Let's chat.

You're doing big things, and big things come with big challenges. We're here to help.

Access the Blog

By clicking the button below you agree to our Terms of Service and Privacy Policy.

levvel mark white

Let's improve the world together.

levvel-mark-mint

© Levvel 2020