Introduction

The REST API principles were a perfect starting point for my foray into programming. Simply put, it appears to be the only option available. The basic answer is that every lesson I followed to learn either the backend or frontend implemented the REST API. It took me some time to begin to realize how many different options there were, and unexpectedly, the great majority of well-known businesses were already utilizing them.

As a backend engineer, it's crucial to have excellent knowledge of web API design. There are a lot of fine details that go into a successful web API. Once you design and build your web API, be it internal or external, it is extremely tedious to make significant changes to it over time. This is why, as a backend engineer, you have to have a really deep understanding of how to design and build a resilient, scalable web API.

In this article, I will be explaining three prominent Request-Response API paradigms that will help you become a solid backend engineer. Fundamentally, APIs can be broken down into request-response APIs or event-driven APIs.

When it comes to request-response APIs, there are three major standards: representational state transfer (REST), remote procedure call (RPC), and GraphQL. Each of these paradigms has its strengths and weaknesses. There is no good or bad among them; it all depends on the use case.

I will be covering each of these paradigms briefly, just enough to make you comfortable using them. I will make references to resources, should you want to go deeper than the scope of this article.

REST API

REST is a set of architectural constraints that stands for "representational state transfer," as described by Roy Fielding in his dissertation. REST is all about a client-server relationship, where server-side data is made available through simple representations of data in simple formats, such as JSON and XML. These representations for resources, or collections of resources, are then potentially modifiable with actions, and relationships are made discoverable via a method known as hypermedia, the concept of providing links to other resources.

Think of REST APIs as basically all about resources. Typically, you would name your resources using nouns. An example of a resource could be "products", with the URL "https://foobar.com/api/v1/products". It is considered incorrect to use verbs like "getProducts" to name your resource in REST APIs. Each resource would typically have two endpoints, one for the collection of resources, like products in this case, and the other for an entity in that collection by specifying the identifier of that entity so consumers would be allowed to use these resources through CRUD operations.

CRUD refers to the four basic operations a software application should be able to perform: create, read, update, and delete. These operations are perfectly suited for REST APIs, as they match the HTTP verbs: POST, PUT, PATCH, GET, and DELETE.

For an API to be considered a REST API, it has to conform to certain criteria:

• A client-server architecture made up of clients, servers, and resources, with requests managed through HTTP.

• Stateless client-server communication, meaning no client information is stored between get requests and each request is separated and unconnected.

• Cacheable data that streamlines client-server interactions.

• A uniform interface between components so that information is transferred in a standard form.

• A layered system that organizes each type of server (those responsible for security, load balancing, etc.) involved the retrieval of requested information into hierarchies, invisible to the client.

Remote Procedure Call - RPC

If the REST API is all about resources, the RPC API is all about actions.

Remote Procedure Call is a methodology used for constructing distributed, client-server-based applications. It is also called a "sub-routine call" or a "function call." Because it is based on traditional local procedure calling, the called process does not necessarily need to be present in the same address space as the calling procedure. RPC works incredibly effectively for client-server interactions when control is sent back and forth. The thread of execution moves from the client to the server rather than running the client and the server simultaneously.

RPC is the earliest and most basic type of API communication. It works similarly to how JavaScript calls a function when given a method name and parameters. The distinction is that it becomes a Web API when used with HTTP or any messaging protocol, such as AMQP.

An API should ideally be created by opening up a set of public methods, which are then made available to the intended consumers via arguments. RPC is only a collection of functions, but they are used in the context of an HTTP API, where the method is contained in the URI and the arguments are contained in the query string or content.

An example of an endpoint would look like this:

https://example.com/api/chat.postMessage - POST Request

https://example.com/api/chat.scheduleMessage - GET Request

https://example.com/api/chat.deleteScheduleMessage - GET Request

The RPC API usually supports GET for read-only requests and POST for other operations.

RPC simply involves sending data fields back and forth when used for CRUD operations, but with a twist—the client is in command of everything. To build its workflow out of otherwise naïve and nondescriptive endpoints, the client must know which methods (endpoints) to call and when.

A modern RPC implementation is gRPC, which can easily be considered a drastically better SOAP. It uses a data format called ProtoBuf—Google's language-neutral, platform-neutral, extensible mechanism for serializing structured data—which requires a schema as well as the data instance, much like the WSDL in SOAP.

I will be writing a detailed article on the gRPC API in the future. So watch out 😉

GraphQL

GraphQL is an RPC with a default process that offers a query language, a little like SQL—if that is something you are familiar with. You can request certain resources and fields, and the system will respond with the requested information.

GraphQL is a query language for APIs that was internally developed by Facebook but has now been widely adopted by leading API providers, including GitHub, Yelp, and Pinterest. You offer a single endpoint as an entry point, which is how it operates. The client specifies the desired data structure, and the server fulfills the request exactly. The GraphQL API only allows POST and GET operations, just like RPC.

An example request may look like this:

{
    Products {
        name,
        price
    }
}

This describes the structure needed to include the name and price fields for a group of products. The server simply provides the name and price fields for each product in the collection that was requested, not anything else.

{
    [
        {"name": "Apple airpods", "price": "5000"},
        {"name": "Samsung chargers", "price": "500"},
        {"name": "Xiaomi Redmi Note 9", "price": "15000"},
    ]
}

The primary selling point of GraphQL is that it reduces the amount of content that has to be downloaded during an HTTP request by default to provide the lowest possible answer from an API.

Summary

One thing is certain, these APIs all have different strengths and weaknesses. They are not to be put side-by-side to determine which is better or weaker. A REST API may boast high flexibility for hardware architecture, and RPC would argue because they are tied to actions directly, payloads tend to be associated with the action itself and therefore tends to be lightweight. GraphQL on the other hand would boast of its ability to retrieve many resources in a single request.

Decisions on the appropriate API paradigm to use for your project should be based on the fundamental architecture needed for the project.

One simple guideline I use is:

• If an API is mostly actions, I should probably be using RPC.

• If an API is mostly CRUD and is having to handle relationships between resources, maybe I should use REST.

• When the project or API is becoming too complex, and too much data is being revealed to unrelated resources, then maybe it's time to convert the project to GraphQL.

I hope you found this article beneficial and that it helps give you more context for understanding some of the API paradigms we have in the modern market.

Let's connect. Follow me on Twitter and LinkedIn.