GraphQL or REST? An Honest Comparison of API Development Approaches

Whether you’re developing an internal tool, a content management system (CMS) integration or an e-commerce plugin, you’ll often find yourself making a choice. Should you use a standard REST API or a GraphQL API?

Facebook developed the GraphQL specification in 2012. Since its public release in 2015, GraphQL has seen widespread adoption by companies building APIs. Though GraphQL is based on and includes many features familiar to REST, there are fundamental differences in the way the two systems handle data.

Do you need to decide at all? As you’re developing an API for clients, you might wonder whether you should develop both kinds of endpoints in parallel. This article explores both of these API development approaches, equipping you with all of the knowledge necessary to make an informed decision about how to approach your next project.

How are these technologies the same?#

The good news is that both approaches use the same technology.

As a developer, you send requests and expect responses over HTTP. You make endpoints available and secure them at an API level for your users. You build servers and your clients query them with their code. So, you need to write efficient code to satisfy your client’s data needs as quickly as possible.

The differences between these API approaches lie in what data they send to the server and what happens when it arrives.

Fetching data#

The first key difference between the two APIs is that a GraphQL API generally has one endpoint that a single HTTP verb queries. However, a RESTful API has many endpoints that multiple verbs can query.

Let’s imagine building an API for a CMS using a RESTful approach. This basic CMS has “posts” that “users” write, and possibly “comments” that other “users” create. When writing this API, you’ll need to create several endpoints:

• GET /api/posts - this endpoint lets clients access all the posts.
• POST /api/posts/:id - this endpoint lets clients create a post.
• PATCH /api/posts/:id - this endpoint lets clients update a post.
• DELETE /api/posts/:id- this endpoint lets clients delete a post.

You’ll also need to create this structure for each of the other resources, “users,” and “comments.”

A typical use case for this API is a client trying to retrieve a post with details about the author, as well as any relevant comments. You have two possible options to support this user. You can create a custom endpoint /api/post-with-details or document the three requests your client needs to make.

Let’s imagine completing the same exercise using a GraphQL approach. The data model and back-end storage are still the same, but you’ll only expose a single endpoint, something like https://api.ourproduct.com/graphql. Your clients will post a GraphQL query to this endpoint. Then, you’ll parse and respond to the query. The request might look something like this:

query {
 posts {
   title
   content
   date
   author {
     name
     byline
   }
   comments {
     content
     date
     author {
       name
     }
   }
}

You can see here exactly what your client is requesting. If they want more or less detail, they can simply edit their query. They control what they want. As their data needs change, they'll use the same endpoint to action their subsequent query.

You’ll still use the same database controllers to gather and organize the data. You’ll “plumb” them together differently, but the large, logical pieces will still be the same.

Providing responses#

With a REST API, your clients always receive consistently structured payloads.

As you design your API, you decide which fields to expose on each endpoint and how to structure the data. As a user-minded developer, you consider how best to group the data and if you need a new route for a specific use case. Creating these new endpoints gives your users fresh views of your data.

Clients may request a custom route for a problem they have discovered that you hadn’t anticipated. You’ll need to decide if it’s important enough to go into your backlog or allow the user to develop their own solution.

A GraphQL response, however, completely matches the request’s structure. The client can design the exact scope and formation of data that they want. This approach reduces the problem of over-fetching (giving the client too much) and under-fetching (requiring your clients to make multiple calls). This more flexible process also allows developers to focus on new fields and data without guessing what clients want.

Creating documentation#

When developing an API, you may find yourself relegating the documentation-writing to the end of the process.

However, it can be beneficial to write documentation first. This approach helps reduce the instances of documentation becoming outdated and ensures that you continue to build relevant features.

Another approach places documentation as the final task in a ticket, ensuring up-to-date examples and documentation. When developing a REST API, using strategies like these keeps your documentation relevant and helpful for your users.

GraphQL takes a slightly different approach.

As a typed API, GraphQL is effectively self-documenting. You can allow your clients to access a GraphQL playground to explore the API and the available mutations and queries. As you update your API, these types update simultaneously.

As this is not a separate process, you can have more faith in the ability of development teams to keep GraphQL documentation up-to-date.

Caching#

Since GraphQL is all served from a single route, having a caching strategy away from the server is more challenging. While some products exist, there aren’t as many well-documented, out-of-the-box solutions.

For a REST-based API, you can provide a route-based caching layer to reduce your server and database loads. These strategies are well deployed and have long been industry-standard practices. GraphQL has some catching up to do in this respect.

When to choose REST#

REST is a battle-hardened solution providing much of today’s Web functionality. It may not be the latest and greatest technology, but this workhorse gets the job done.

Generally, REST is the correct choice when applications request your data in predictable and understandable ways. If the tool you are building is likely to integrate with other tools, such as a low-code platform, then REST is often a better solution. Bubble, Zapier, and others have good support for integrating with REST-based APIs.

When to choose GraphQL#

GraphQL is rapidly increasing in popularity, particularly among front-end developers.

If your data is flexible and can be queried in several different and unpredictable ways, such as with a CMS, then GraphQL is probably the better bet.

Allow your users to decide, rather than trying to anticipate how they will want your application to present the data and expose the various fields. Give them control of your well-documented API.

Conclusion#

Both REST and GraphQL are excellent technologies enabling development teams to build innovative and exciting projects around the Web.

REST’s stable and well-known architecture offers familiarity and enables developers to be productive quickly. GraphQL is flexible and self-documenting, allowing users to employ APIs customized to their specific needs.

Transposit’s connected workflow platform for DevOps enables you to integrate with anything through our API-first architecture and 200+ pre-built integrations. Curious about how Transposit improves visibility, context, and actionability across people, processes, and APIs? Request a demo.