Rapid CTO: Understanding the balance between REST vs GraphQL APIs
This is a contributed piece for the Computer Weekly Developer Network written by Alex Walling in his capacity as field CTO at Rapid.
RapidAPI by Rapid (the company itself was previously known as RapidAPI but now goes by Rapid to distinguish the product from the organisation) is said to be the ‘world’s largest’ API Hub, where over four million developers find, connect, build and sell tens of thousands of APIs.
Choice is generally viewed as a good thing, but at some point it can become overwhelming – and that rule can certainly hold true in the API world. As APIs continue to proliferate, so do their types: REST, SOAP, GraphQL, Kafka-based APIs, Publish/Subscribe Pattern-Based APIs, Remote Procedure Call protocols and Webhooks, among them.
Walling weighs up the choices software application developers now face and assesses the state of the API marketplace for us in some depth – he writes as follows…
Why API?
Before choosing the best API for a given job, consider these questions: is performance, scalability, or reliability your top requirement? Or does the API need to help simplify the development process or make it easy to modify the code?
Other distinctions also matter, including the very nature of the API. Some are based on architectural styles (REST) while others are frameworks, or query languages (GraphQL).
Let’s take a closer look at two types of APIs commonly used in mobile and web applications: REST APIs and GraphQL.
REST APIs
REST (REpresentative State Transfer) is an architectural style that Roy Fielding introduced in 2000 that’s largely driven the API economy. REST APIs call resources and allow software to communicate using standardised principles, properties and constraints.
REST APIs operate on a simple request/response system. The request includes the HTTP method (GET, POST, PUT, PATCH, DELETE), endpoint, headers, URL parameters and the body. The response returns the relevant data, which can be formatted as JSON, XML, plain text, images, HTML and more.
RESTful APIs can be designed with many different endpoints that return different types of data. However, accessing multiple endpoints with a REST API requires multiple calls, which can slow down performance.
RESTful APIs are easy to learn and so common that most developers are familiar with them. Most platforms and frameworks have built-in libraries capable of interfacing with REST APIs, so they are very interoperable. They’re also reusable, so you can easily create independent microservices that work independently of one another. They are decoupled from clients and accessible by multiple applications.
On the downside, a RESTful API architecture ties the resource type to the method used to retrieve it. Because there’s a separate endpoint to request each resource type, you have less control over the exact data you’re fetching because the object structure is hardcoded into the server. That means data is over-fetched in many situations, leading to slower loading times.
Walling: APIs come in differnt forms – some are based on architectural styles (REST) while others are frameworks, or query languages (GraphQL).
Let’s take a simple example of fetching data from an API about a company (name and location) and its founder. With a REST API you have to run two separate queries to retrieve this data. The first query is GET /company to retrieve all the company information. In response, you would need to pass a founder_id to the GET /founder request to return all the data associated with the founder. Of course, most real scenarios are much more complex and require many more requests to fetch data.
To summarise, RESTful APIs are best for applications that have simple data structures or only need a few sequential requests to fetch the required data. For projects with complex data structures and many different requests, GraphQL might be a better fit.
GraphQL
GraphQL is an open source query language that Facebook developed in 2012 to implement the News Feed section for its iOS app. The News Feed needs to request so much data (posts, profile images, comments, likes etc.) that many bugs were occurring because there was no convention for data exchange between the multiple front and the backends.
Unlike REST APIs, GraphQL APIs only have a single endpoint to retrieve all the required data for an app. GraphQL’s biggest strengths are that they let you control exactly what data is received from the server in a predictable structure and use a single request to fetch data from multiple sources.
Let’s take our first example.
To fetch the data about the company and its founder with GraphQL, you only need to run a single request to the server. This is because GraphQL relies on a strongly-typed, predefined schema that allows the client to specify the exact shape of the data returned. The schema defines a structure for how the data — populated from back-end data stores — is formatted and nested. Then, as part of the request to GraphQL, you can decide exactly what data your applications require from this schema.
This ability to define the exact request and response structure also cuts down on the resources and bandwidth required to fetch data, as only the desired data will be included in the response. GraphQL APIs are a great choice if you deal with complex data structures and need to request different data sources.
The downside of GraphQL is that it’s relatively new and less familiar. Also, depending on the use case, setting up the schema can be more complex than the simple REST requests. Fortunately there are many starter kits and examples available on how to structure GraphQL projects.
Although GraphQL continues to grow in popularity, it isn’t right for every situation. Before choosing between REST or GraphQL, it’s worth investing some time to analyse your available resources and define your application’s needs. To help make your API choice a little less overwhelming, I’ve described in detail how we chose GraphQL for our RapidAPI Hub in this blog post.