API Paradigms — which and when to use them: REST vs RPC

Lately, I’ve been working a lot with APIs, and the time to create a new API from scratch came. I wanted to create a sustainable, robust, and long-lasting API to endure in time, so I asked myself: “Is REST the best way to do this?

I started to search over the internet. Even though RPC is considered an outdated paradigm, others may think these are times to shout out at API developers to look around to other paradigms besides REST. RPC is starting to grow their fan group again, so it seems. Now even more with JSON-RPC as a simplified alternative to the old RPC in XML.

I got intrigued and realized I need to know more about API foundations to make my decision properly. So I decided to share my notes with you, taken mainly from the book published by O’Reilly — “Designing Web APIs” by Brenda Jin, Saurabh Sahni, and Amir Shevat some websites listed at the end of this post.

There are two main API categories: Request-Response and Event-Driven. Let’s start with Request-Response APIs! And we’ll get to the Event-Driven APIs in the next post.

Request-Response APIs

As the name suggests, in this type of APIs, the client requests data to an endpoint, and the server returns the response. These requests are commonly made using the HTTP protocol but remember others exist, and you should choose which one fits you better.


This category houses three paradigms: REST, RPC, and GraphQL. I knew from the start that GraphQL wouldn’t be my choice, so I got to confess that my research about it was poor. So I decided just to expose the information in the book, and I believe that will be enough for most of you. But don’t hesitate to comment if you want more about it 😉.

REST

REST stands for “REpresentational State Transfer,” and it’s all about resources. What does this mean? It means it exposes data as resources. A resource being an entity that can be identified, named, addressed, or handled on the web. It also uses HTTP methods to represent CRUD (Create, Read, Update, Delete) operations and, as REST focuses on uniformity, if you’re using HTTP, you should use HTTP features whenever possible.

There are two other main constraints: it should be stateless, which means not persisting sessions between requests, and the responses should declare cacheability to help its scalability.

Usage standard

As we already know from the above mentions, REST uses the HTTP verbs to indicate the type of CRUD operation to perform. To use it, you should provide the HTTP verb that fits your operation. In the URL, you provide the resource over each operation is applied. The details are given as parameters or/and within the body.


A noun instead of a verb must represent a resource. For example:

/users/123

Instead of:

/getUsers/123

Error codes standard

Another cool thing about REST is that it provides a code called “status code” within the response to let you know whether the operation succeeded or not. The set of error codes it might return is standardized, and you can check it in the following cheat sheet:

Status CodeMeaning
2XXSuccess
3XXA resource has been moved
4XXError from the client-side
5XXError from the server-side
Error codes standard

RPC

RPC stands for “Remote Procedure Call” and, with this paradigm, the client can execute a block of code on another server, passing the method name and the arguments in the request. Simple, isn’t it? 😁


Unlikely REST, RPC doesn’t provide a status code, so you need to analyze to response to check if the operation was successful or if it wasn’t, which can be annoying or not, depending on how you programmed the return of the procedure you sent the request to run.


To give you some context before continuing, RPC was popular in the past but lost its popularity to the simplicity the REST came to hand with JSON calls instead of XML, which could be hard to debug and maintain. Now RPC is catching up again with JSON-RPC. In this post, when I say RPC, I mean JSON-RPC. We will see later some request examples to compare with REST.

Usage standard

As we saw, the call looks pretty simple, keeping in mind that the endpoints contain the resource name and the method/operation to be executed in its URL, and the method arguments are sent in the body with JSON structure.


It’s common to call the procedure using a combination of resource and method to give a context, such as:

/user.create

Instead of:

/createUser

This way, you’re helping the API user and the developers if the code has a similar structure being, for example, User a class and create a method of the class User. And you also know that you will use as many endpoints as the action you want to perform.

GraphQL

GraphQL can be described as a query language for APIs and, so, the requests are sent in the form of a query.

Usage standard

Having said that, it needs only a single URL endpoint and, as such, doesn’t require multiple HTTP verbs to describe the operation. The JSON body has the operation information to perform. This is getting simpler and simpler, isn’t it? 😏

Summarizing

RESTRPC
DefinitionExposes data as resources; To represent CRUD operationsExposes action-based API methods
Use CaseFor APIs doing CRUD-like operationsFor APIs exposing several actions
HTTP verbsPOST – Create
GET – Read
PUT – Update
PATCH – Updated
DELETE – Delete
GET – read-only response
POST – others
Pros* Standard method name, arguments, format, and status codes
* Uses HTTP features
* Easy to maintain
* Easy to understand
* Lightweight payloads
* High performance
* Not exclusive to HTTP protocol
Cons* Big payloads
* Multiple HTTP round trips
* Discovery is difficult
* Limited standardization
* Can lead to function explosion
Usage interpretationIt’s more like a post-action:
* First, you create a resource in an existing collection
* Then, the action is performed in the background through a trigger
Triggers an action to perform the request
REST vs RPC

Payloads

For smaller requests (and responses) payloads, REST might be more suitable, but if you feel you need more scalability, RPC can be the solution.

Remember: overhead is the extra processes or resources required to perform a specific task (Wikipedia).

Even though RPC has more overhead than REST, in the end, the payload may compensate for this on a large scale. Let me explain this better with an example: Assuming the overhead in communication is constant or suffers light variations, the more payload you expect to send and/or receive, the more will RPC be better than REST because RPC often uses protocol buffer, which is a mechanism for serializing structured data reducing the large scale payloads. Check out the following image for details:

Payloads: REST vs RPC

Remember: payload is the message itself transmitted from client to server (request payload) or from server to client (response payload) (Wikipedia).

RPC discoverability and function explosion

Just two quick notes to explain to you better these cons from RPC.

discoverability

In RPC, the discovery is difficult. This is because there are no standards – it depends on the API code development. Without adequate documentation, you won’t know how to start neither what to call. This is more like a warning rather than a con.

function explosion

Again, a code development warning! Creating functions and more functions can be a common thing in a developer.

REST vs RPC: request calls

Let’ say I want to create a new user. There are differences between code request code and also in their interpretation:

Using REST:

POST /api/user/create?userid=0123456 HTTP/1.1 Host: localhost:808 Content-Type: application/x-www-form-urlencoded

We are creating a user resource in the users’ collection. The nuances of its creation are set and done in the background.

Using RPC:

POST /api/user.createHTTP/1.1 Host: localhost:808 Content-Type: application/x-www-form-urlencoded userid=0123456

or even:

{ "method": "user.create", "params": { "userid": "0123456" }, "jsonrpc": "2.0" }

With RPC, it feels more like we are immediately creating a new user with no intermediate steps.

And that’s it! ✌️

So, what makes an API great? It varies from the API goals and use cases and even the developers, but it can be resumed into three words: usabilityscalability, and performance. So choose wisely! 😉

I really hope you liked it. I certainly enjoyed sharing this with you! If you did, please share and/or comment.

Credits

Leave a Reply

Your email address will not be published. Required fields are marked *