REST API vs GraphQL
Overview
Before exploring the differences between REST and GraphQL, it’s important to note that there are a multitude of network APIs other than these two. Common alternatives are noted in Other Alternatives.
This post is not going to dive deep into the details of each technology. Instead, it’s going to focus on the differences and use cases. Links will be provided to dive deeper on the individual protocols.
Table of Contents
GraphQL
The primary use case of GraphQL is as an interface for Front-End clients when communicating with a Back-End server. Its advantage over REST is because a Front-End client typically requests many resources of different types to populate a page with data. GraphQL enables you to build a single query with resources of different types and send that query to a single HTTP endpoint. This greatly reduces the number of requests sent from the Front-End client (to just one), which speeds up page loads.
Front-End to Back-End
Back-End to DB (or more typically other Back-End services)
Note 1: The datastore could be another service.
Note 2: It’s unlikely a customer’s orders, delivery addresses, and payment methods would all exist on the same page.
Each node resolves its object as defined in its resolver function. An example of this in code for Python can be found in this library’s API (Graphene). The above tree (also technically a graph) is not an Abstract Syntax Tree (the most important data structure in GraphQL). The AST represents the entire user query, including all fields (like scalar fields such as strings which are omitted in the tree above), as well as conditional constructs, such as ... on someField { someSubField } (more details on fragments here).
Authorization and Authentication
Another great GraphQL feature is its middleware, which effectively wraps each GraphQL node with some logic before calling the node’s resolver. This feature is great for implementing fine-grained authorization (and more). For a code example in Python, see this library’s API (Graphene). Authentication should likely happen further upstream from node-level middleware handling and this article does a great job explaining where to place your GraphQL authentication.
Ease of Implementation
Implementing GraphQL requires developers that have a good understanding of basic computer science, especially in regard to tree data structures. This requirement is necessary for understanding and working with GraphQL’s fundamental building blocks (namely the AST).
REST
While GraphQL’s main purpose is an interface for Front-End applications when communicating with Back-End servers, REST APIs can be used for both Front-End (client) to Back-End (server), as well as Back-End (client) to Back-End (server).
Although not technically necessary, adhering to the REST implies using the correct HTTP request method for each type of action: fetching (GET), creating (POST), updating (PUT or PATCH), or deleting (DELETE).
Authorization and Authentication
The possibilities are endless for implementing authorization and authentication. This article does a great job of providing an overview of the top authentication protocols used in REST. This blog post touches on best practices for REST authorization.
Ease of Implementation
REST APIs are very easy to implement, even by novice developers. Although libraries exist to expedite building them, they’re not required. Basic libraries to help building and handling HTTP requests will suffice. Just search for request libraries in the language of your choice.
Other Alternatives
The most common alternative is found in distributed computing, and is some variation of RPC. Some implementations of RPC are:
Another alternative in distributed computing would be messaging, such as Apache Kafka or Amazon SQS. See Throughput vs Latency for a better idea of when to use messaging. There also exist plenty of niche, dated, or proprietary network APIs that are not worth mentioning.
Author
Sam Malayek works in Vancouver, using this space to fill in a few gaps. Opinions are his own.