RESTing: Part III - REST, RPC, SOAP, GraphQL and what else?

Last part - in the series of RESTing. As part of this blog, we will examine when an API is RESTful and what are alternatives to REST.

(Also read RESTing Part I and RESTing Part II)

REST and RESTFUL

APIs are dominating the world of software engineering and we are throwing these two terms, REST and RESTful, interchangeably. Are they really the same or there is a demarcating line between them? The answer is easy when your APIs are following REST principles they are Restful. So what are the REST principles?

Basic principles of REST

• Statelessness: Requests are independent and their states cannot be maintained. Advantage - Improves performance and security.

• Caching: The client can store data that can be accessed frequently. Advantage - Improves application performance and lowers server latency.

• Uniform Interfaces: Standards set by the server as a contract between the server and client application for identifying resources (see RESTing Part I), manipulating resources, sending hyperlinks and using MIME types. Advantages - Consistent URI, idempotent method behaviour, predictability and informative approach.

• Decoupling between client and server: Client and Server are independent, providing flexible architecture. Advantages - Flexible, well maintained and scalable architecture.

• Layered architecture: Architecture where components with the same objectives are grouped together. Advantages - Provides security and better performance.

• Code on Demand: Possible to send executables in the form of a response. Advantages - The client can extend its functionality as per need.

Examples of REST API

• Stripe API: As the documentation goes - "The Stripe API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs."

• Jira REST API: Documentation can be found here - "The Jira REST APIs are used to interact with the Jira Server applications remotely, for example, when configuring webhooks. The Jira Server platform provides the REST API for common features, like issues and workflows."

• Twitter API: For more on its documentation please visit this link.

These are a few examples where REST principles are followed and API can be used to integrate their services in the applications you are developing.

Alternatives to REST

In addition to REST, there are many other options, such as SOAP, Websockets, Event-based architecture, FALCOR, GraphQL etc. Since I'm a bit biased toward REST, I'm going to pick a few that managed to share the same glory and try to compare. Please note, this is based on personal opinion.

RPC

Even though Remote Procedure Calls and Webservices are decades old, they remain in business relentlessly and proudly. They are excellent examples of low-overhead and high-performance messaging. In addition, they have laid the foundation for SOAP. Comparison is made in the table below, and although RPC is not very common in use, it does have an important position as it has shown the path for remote method invocations. To choose from, RPC has various implementations based on data formats including JSON-RPC, gRPC, XML-RPC, etc. These extensions of RPC are mainly the protocols. With various advantages and drawbacks associated with each protocol, it is easy and difficult both at the same time, to find the one that is most suitable for your needs.

SOAP

SOAP (Simple Object Access Protocol), is an Initiative by Microsoft and some other big companies to solve the problem of internet communication between applications built in different languages and using different platforms. As per the name, it is a protocol which works on strict communication contract. Being a bit older as compared to REST, SOAP is rigid and only allows XML messaging. It exposes the remote procedures and functions while REST is data-driven. SOAP web services offer built-in security and transaction compliance that align with many enterprise needs, but that also makes them heavier. (For more comparison details please refer to the table below.)

GraphQL

GraphQL is an open-source query language for APIs. It came out very strong while handling JSON responses. It tried to overcome some of the shortcomings of REST. With REST, multiple endpoints need to be created to fetch different sets of data. Ex: to fetch books (GET /books or GET /books/{id}) or to create web articles (POST /articles) or delete subscriber (DELETE /subscribers/{id}) 3 different endpoints will be required in REST. GraphQL on the other hand offers a single query to perform all these operations. In the world of REST, every endpoint returns a fixed data structure of the response. It can have some information that clients might not need (over-fetching problem) or it might not have all the information and the client needs to make another different call for missing information (under-fetching and n+1 problem). While with GraphQL, you can specify how much data you are interested in. That way over-fetching or under-fetching or n+1 is avoided.

With all that sounds perfect, GraphQL can add performance issues with complex queries. Also with no unique url pattern, GraphQL cannot provide support for HTTP Caching. For smaller applications, REST came out as a better choice while GraphQL appeared too complex. Overall you can use GraphQL and REST interchangeably to have the best of both worlds, while there are times when it is better to study and find what suits your application best.

Conclusion

	​REST	RPC	SOAP	​GraphQL
Definition	Architectural style to design APIs, that helps communication over network possible and involves resources.	Architectural style to design APIs, that helps communication over network possible and involves procedure calls using stubs for the remote procedure.	Protocol to communicate between different applications over the network.	Open-source query language for APIs for exchanging data over network.
Statefullness	Stateless.	Stateless and Stateful, supports both.	​Stateless.	​Stateless.
Opertations	CRUD, create, read, update and delete of resources.	​Can perform actions on remote servers.	CRUD, create, read, update and delete of resources.	​To get read-only data queries are used. To modify data mutation is used.
​Data format	Supports multiple data formats, independent of server. (Json, xml, html etc)	Data format is enforced by sever.	Supports XML.	Supports multiple data formats. (Json, xml, html etc)
SSL/TLS security for encrypted communication	Supports.	By default RPC uses TCP/IP or UDP. Although gRPC has default feature to support SSL/TLC protocols.	Supports.	Supports.
​When to use	To perform stateless operations with high performance.	To perform complex operations.	To integrate legacy systems that already uses SOAP.	​Applications where bandwidth matters and different types of nested data need to be fetched with single call. Ex: apps for cell phone, smart watch etc.