5. Communication protocols

The Problem

Your clients (users) will communicate with your application (monolitic or micro-services) using communication protocols and standards.

Depending on your application functionnal requirements and non-funtional requirements, some protocols might be more efficient than other to provide a better user experience.

We'll quickly remind the fundamentals of communication protocols with the OSI model, then we'll introduce the common and standard solutions for a client to send/receive data to/from a server.

OSI Model

Every computer communicating with each other on a network use the OSI model. It was invented to provide a better standardization to allow differents systems to communicate with each others. As described in the following diagram there is 7 layers.

When a computer communicates with another, in reality, the application and data is encapsulated within each layer from one side, starting from the Application layer all the way to the Physical Layer, and decapsulated on the oher side.

Most modern applications are web applications, and the client communicates with a server using the HTTP protocol (Application Layer).

Clients (HTTP Client) send/receive requests to/from the server (HTTP Server).

With the evolution of the applications and their complexities, standardization have been implemented to ensure better reliability when client send/receive data to/from server.

The Application Programming Interface (API) is the most used standard to exchange data between a client and a server.

5 main API architectures exist today and can be used by application developer to provider better reliability and improve user experience.

RESTful

GraphQL

WebSockets

Let's dive in each of them and provide the best uses cases where they can be implemented.

RESTful

REST (Representational State Transfer) has been invented in the early 2000, and since then has become the standard way to send or retrieve data to/from a server.

The main advantage of the REST API model, is to provide a consistent way to produce ad consume APIs.

Developers use the HTTP methods (POST, GET, UPDATE, DELETE) to perform the CRUD operations (Create, Read, Update, Delete)

RESTful API Use cases: Due to their flexibility, developpers use REST Apis is used mostly for :

Cloud Applications (CRM, Inventory, Financial)

Cloud Services (All the cloud services are based on RESTful APIs )

Web use (You can have different stack for your clients : iOS application, IoT Device, .. )

Benefits of using RESTful APIs

Flexibility and scability: The separation between client/server, provide more flexibility to develop your product (web application) and you can easily make migration from one server to another

Independence and small size: Due the separation between client and server, you can easily perform test with different environments or client stack. It supports multiple format to send data (JSON, SOAP, HTML) which does not take much data

Challenges of using RESTful APIs

REST endpoint consistency: As the number of your APIs increase, you might have hard time keeping consitent endpoints if many developers are involved.

REST API versionning: Best practices is to provide versionning for your API to prevent service interruption; You may have some challenges to maintain multiple versions.

REST API Authentication : To secure the access to your APIs, you may have to provide many authentication options:

HTTP authentication (Basic authentication, Bearer authentication)

API Keys (your user provide an api key to authenticate to your apis service)

OAuth (provide more robust secure by combiening password and token)

REST API Security : The common challenges you may have when implementing RESTful APIs Security :

No rate-limiting (if you don't set a limit on user requests, you can exhaust your resources)

Weak API keys (if api keys are not strong enough, they can be compromised )

Unnecessary requests and data : You may send multiple requests to retrieve data which is not needed by your client/application.

GraphQL

GraphQL is query lanquage for your APIs, it will provide to clients the option to query only data they need.

GraphQL Real-World Use cases: Most of the time GraphQL is used for :

Mobile and Web applications

Data aggregation

Let's explore with 2 use cases the difference between GraphQL and REST API.

Use Case 1 : Our goal is to retrieve only the required data we need from an api endpoint. Let's see the difference between RESTFul API and GraphQL.

Example : With RESTful API

(1) A client sends an http request to the api endpoint, to retrieve the resource with the id=1;

(2) The response contains all the information for the resource id=1 :

"title" : "The Pragmatic Engineer"

"isbn" : "2233444222"

"authors" : ["David Thomas", "Andrew Hunt"]

Now let's see how it works if we use GraphQL query.

Example : With GraphQL

Like illustrated in the following diagram :

(1) The GraphQL client sends a request to the api endpoint, to retrieve only the title for the resource id=1

(2) The API endpoint sends a response with only the data requested

"title" : "The Pragmatic Engineer"

Use Case 2 : Our goal is to retrieve data from multiple objects (example from books, users, orders ) from an api endpoint. Let's see the difference between RESTFul API and GraphQL.

Example : With RESTful API

Like illustrated in the following diagram :

(1) A client sends a request (x3 HTTP requests) to retrieve the book with id=1, the user with id=15 and the order with id=5;

(2) The API endpoint sends a response with all the data objects

Example : With GraphQL

Like illustrated in the following diagram :

(1) A client sends a request (only x1 HTTP request) to retrieve from the book object, the "title" with id=1, from user object, the "username" with id=15 and from order object, the "order_date" with id=5;

(2) The API endpoint sends a response with only the requested data.

Benefits of using GraphQL

Not overfetching or underfetching: To main advantage of GraphQL in contrast to REST API, is the fact that it returns with a single query the exact data required by the client, it does not return more or less data.

Faster response time: GraphQL allows client to send multiple requests in a single query, make it faster than REST API; Your client sends the query (combination of multiple requests) to a single endpoint.

Challenges and Limits of using GraphQL

Lack of proper HTTP Error response: GraphQL query will always return a HTTP/200 OK response, whether the query is successfull or not.

Lack of caching: GraphQL does not have built-in caching mechanism like REST API. You need to use external libraries.

Security: As client can perform multiple queries on a single endpoint, you may have issues or performance and may be exposed to DoS attacks, when queries are really complex.

According to the 2023 State of API report, 86% of developers use REST, and 29% use GraphQL.

WebSockets

WebSocket is a communication protocol enabling bi-directionnal, and real-time communications between a client and a server over a single TCP connection.

The client will initiate a connection using an HTTP Request (GET) with a "upgrade" header .

WebSocket Real-World Use cases: Due to the powerful real-time communication capibilities, WebSocket is often use for the following:

Stock Exchanges (real-time updates of stock prices, orders, etc..)

Chat applications (sends and receives real-time messages)

Gaming applications (real-time interaction between the player and the game hosted on the server)

Benefits of using WebSocket

Low Latency: WebSocket use a single TCP connection, offering better network performance between client and server. There is only one TCP Handshake, while other with REST, multiple TCP connections and multiple Handshakes are required.

Bi-directional: A single TCP connection allows client and server to send messages until one decide to close the connection.

Challenges and Limits of using WebSocket

Complexity: WebSockets can be complex to implement depending on your use cases.

Firewall / Proxy : As a single TCP connection is allowed to authorize multiple bi-directional messages between client and server, it may bring more challenges for firewall or proxies configuration.