gRPC, Restful API, GraphQL, Web Socket, TCP Sockets and UDP, WebTransport — Beyond modern client server communications
By: Amir Kamali
Tags: GraphQL, Websocket, Grpc, Open Api, Webtransport

Architecting a distributed system requires a good understanding of available technologies. Each technology can be used like a tool in a toolbox to solve real world problems. In this article, I will discuss modern protocols and frameworks with their pros and cons along with some tips and tricks of using them are explained. Additionally if you’re interested in finding the latest trends, I have included the future standards and technologies that will soon be available.

REST API:

Rest APIs are the simplest and most common way of communication between a server and a client. REST is acronym for REpresentational State Transfer. The technical implementation of REST APIs is not the purpose of this article. However, if you’re interested in learning more I have included some good references at the end of the article.

Using Http protocol clients can use different verbs such as GET, PUT, POST, PATCH and DELETE to access or update content on the remote machine.

HTTP GET /devices?startIndex=0&size=20

HTTP POST /configurations

HTTP DELETE /configurations/{id}

It is important to note that REST API’s are stateless due to the nature of HTTP protocol. This means every time that a client makes a request, it has to identify itself usually by carrying a token or session-Id so that the server can identify and process the request.

Advantages of Rest APIs:

RESTful APIs were designed based on HTTP Protocol. This means that developers have no need to install additional software or libraries when creating a REST API.

One of the key advantages of REST APIs is that they provide a great deal of flexibility. Data is not tied to resources or methods, so REST can handle multiple types of calls, return different data formats and even change structurally with the correct implementation of hypermedia. This flexibility allows developers to build an API that meets your needs while also meeting the needs different customers.

Most modern APIs use Json/XML format to send and receive data and unless the body is not encrypted, it is easy to read the content of the request and response for testing and debugging.

Limitations of Rest APIs:

REST APIs are great when you just to access or write data at some point of time but it is not built for streaming content or real time communications.

REST APIs are also defined based on concrete contracts. This means adding and removing parameters in the request or response needs changes in both client and the server. In large companies with a lot of different APIs, maintaining and having backward compatibility is a challenge on it’s own.

Testing RestAPIs:

One of the great free tools out there for testing Rest APIs is Postman. Postman is great to make a request or orchestrate a set of requests to simulate the behavior of the client without the client being built or present.

image from postman.com

Open API (Swagger):

Writing and maintaining contracts, developing DTOs (Data Transfer Objects) and documenting them has always been a challenge across teams. Swagger was originally introduced originally in 2010 and later renamed to Open API standard in 2015 to streamline this process. Open API is now widely used by a lot of major companies such as Amazon, Google, Microsoft, etc.

Using Open API, backend teams can design an API technical specification in YAML or JSON format which can contain all the information about routes, parameters, security as well as documentations. The great part of using Open API is the code generators. After defining the API Specifications, both backend and client side teams can generate the source code for the networking layer. This reduces developers’ time for implementing, testing and debugging communication issues between both sides.

Designing API Specifications:

Swagger hub: Swagger hub is an online tool designed by swagger.io which allows you to design, test and export your API specifications online

Stoplight: Another online tool to design APIs and DTOs as well as adding documentations. Stoplight has a lot of great features when it comes to defining API securities, validations, exporting, etc. It is my preferred tool to design and export API specifications.

GraphQL:

GraphQL is query format language that was publicly introduced by Facebook in 2015 with the goal of minimizing transferable data. GraphQL offers great flexibility for the client to query the server in any acceptable variation and receive the response without containing other unnecessary data.

Since GraphQL became public, it has been widely used in production by a lot of major companies such as Facebook, Credit Karma, GitHub, Intuit, PayPal, the New York Times and many more. A number of people and companies have implemented GraphQL standard. Some popular implementations include Apollo and GraphQL.org

GraphQL has been built on top of RestAPI. This means, it comes with all the great benefits of REST API and can be debugged easily. You can find the sample GraphQL query and the response in below:

GraphQL Sample Query

GraphQL Sample Response

Limitations of GraphQL:

While GraphQL has a lot of benefits to simplify the request, it adds a performance overhead that needs to be considered.

Complex views can still trigger multiple database calls, which in turn can make for slow loading times. There are few approaches to resolve these issues such as using Data Loaders, caching and aggregating queries.

Debugging GraphQL:

Postman is has a good support for GraphQL and allows you to test your GraphQL queries similar to REST APIs. For more, check out GraphQL Queries using Postman.

Web Sockets:

WebSocket is a communication protocol which features bi-directional, full-duplex communication over a persistent TCP connection.

Web sockets is a great solution for chat applications, financial market apps and web browser games that require live data communication between a server and client over HTTP protocol. There is limited HTTP overhead (like headers, cookies, etc.) making data transfers possible at a much higher rate.

Limitations of Web Sockets:

Illusion of reliability: Unlike HTTP, Web socket connections can be unreliable due to connection issues. In real world scenarios, it’s always good to have a solution in place to recover any lost messages.

Load balancing issues: Unlike HTTP servers where horizontal scaling is possible, there is no standard way to scale web socket servers. This is because each client needs a persistent connection with one server to communicate. There are custom implementations such as N-CHAN that allows you to overcome this problem.

With the advances of HTTP protocol, web sockets are not supported in HTTP/2.0. New protocols such as WebTransport will soon become available to address this issue. WebTransport can offer standardized live communications over different versions of HTTP Protocols.

TCP Sockets:

In OSI network layers TCP socket operates in a Session layer below the Presentation Layer. This allows a great flexibility when the performance is a factor for the communication. Unlike RESTful APIs, in TCP sockets the integrity of the connection can be verified during the handshaking process without repeated verification of the identity in each message. This process can continue as long as TCP connection remains opened. Since there’s no HTTP headers available in TCP connections, TCP socket can offer a high throughput and low latency communication between server and clients.

OSI Networking Layers

It is important to note that TCP layer guarantees the delivery of network packets. TCP socket is a reliable protocol which is great for precise applications such as online gaming, monitoring systems, sensors, remote surgeries, etc.

Limitations of TCP Sockets:

Scaling: While TCP has a great performance scaling TCP sockets and load balancing can be challenging.

Debugging: In TCP sockets, messages are binary and unlike REST API, it’s not easy to view and edit the body of the requests.

gRPC:

gRPC or Google-RPC is a new CNCF standard based on HTTP/2. It has been introduced by google to enable high speed binary communication between the client and server. Using gRPC, a client application can directly call a method on a server application running on a different machine as if it were a local object. This makes it easier for you to create distributed applications and services. As in many RPC systems, gRPC is based around the idea of defining a service, specifying the methods that can be called remotely with their parameters and return types. On the server side, the server implements this interface and runs a gRPC server to handle client calls. On the client side, the client has a stub (referred to as just a client in some languages) that provides the same methods as the server.

image from https://grpc.io

gRPC has a lot of great features such as Bi-directional streaming and great scalability. Similar to Open API, after defining a specification file (aka .proto file), both the client and server can easily use a code generator to implement the network layer of the applications.

gRPC offers upto x10 faster communication comparing to REST APIs due to the nature of binary communication and benefits of HTTP2. In 2019–2020 a lot of major companies have invested in supporting gRPC and migrating the REST APIs. It is expected to be a big trend in the coming years.

As illustrated in below diagrams, the performance of gRPC is much higher in comparison with REST APIs within different scenarios.

image from https://github.com/david-cao/gRPCBenchmarks

image from https://github.com/david-cao/gRPCBenchmarks

Limitations of gRPC:

Since RPC calls are binary format, testing, debugging and editing the request can be challenging.

Designing gRPC Proto file:

Proto file is a catalog that defines the method and arguments required to initiate a gRPC call between the client and server.

Sample Book Service design

Migrating from REST API to gRPC:

If you have isolated your API DTOs and networking layer, it should be straight forward to translate the parameters and define messages in .proto file. You can then use the gRPC generator to re-create the network layer in gRPC.

If you have incorporated OpenAPI in your system, there are some open source tools that can generate .Proto file based on your OpenAPI spec file.

gnostic-grpc: Designed by Google internship students as a plugin extension for Google’s gnostic tool. Personally, I had some issues while migrating some of the API’s defined in Open API.

openapi-proto: open sourced by NY-times, I personally found it more helpful than gnostic-grpc. However, this tool is not a complete conversion tool and you might encounter some problems.

Debugging gRPC:

Bloom RPC : If you’re planning to implement gRPC, Bloom RPC is a great open source tool to test and debug RPC calls. It offers features similar to Postman to initiate and test gRPC calls.

gRPC is still a very new protocol. While there aren’t many testing tools available yet, it is expected to see a lot community contributions in the near future.

New protocols in town:

WebTransport:

Web transport is a new protocol that has been introduced to fill the gaps between HTTP/2, Websockets and UDP like connections. It also that allows web applications to establish interactive, bidirectional, multiplexed network connections. WebTransport has the compatibility with HTTP3 and it is proposed to be compatible with QUIC protocol.

WebTransport supports multiple features which some of them are highlighted in below:

Unidirectional streams are indefinitely long streams of bytes in one direction with back pressure applied to the sender. This is when either receiver can’t read quickly enough or it is constrained by network capacity or congestions.

Unidirectional streams can be useful for sending messages that do not expect a response. In-order, reliable messaging can be achieved by sending many messages in a single stream. Out-of-order messaging can be achieved by sending one message per stream.

are indefinitely long streams of bytes in one direction with back pressure applied to the sender. This is when either receiver can’t read quickly enough or it is constrained by network capacity or congestions. Unidirectional streams can be useful for sending messages that do not expect a response. In-order, reliable messaging can be achieved by sending many messages in a single stream. Out-of-order messaging can be achieved by sending one message per stream. Bidirectional streams are full-duplex streams. A bidirectional stream is effectively a pair of unidirectional streams.

are full-duplex streams. A bidirectional stream is effectively a pair of unidirectional streams. Datagrams are small, out-of-order, unreliable messages. They are useful for sending messages with less API complexity and less network overhead than streams.

Web transport is great for many applications. Some highlights are:

Sending or receiving low-latency media

File transfers

Sending game state with minimal latency to server in many small, unreliable, out-of-order messages at a regular interval

Receiving media pushed from server with minimal latency (out-of-order)

Receiving messages pushed from server (such as notifications)

Requesting over HTTP and receiving media pushed out-of-order and unreliably over the same network connection

Web Transport is still at early stages and requires implementations and support in various languages.

Quic:

QUIC (Quick UDP Internet Connections, pronounced “quick”) is a general-purpose transport layer network protocol similar to UDP. Quic was initially publicly introduced by Google in 2013. While still an Internet Draft, QUIC is used by more than half of all connections from the Chrome web browser to Google’s servers. Microsoft Edge, Firefox and Safari support it, even if it’s not enabled by default. QuicTransport maps directly to QUIC streams and datagrams, which makes it easy to connect to servers that speak QUIC with minimal overhead.

Datagrams:

Datagrams are individual packets of data that are limited in size by the maximum transmission unit (MTU) of the underlying connection, and may or may not be transmitted successfully. If they are transferred, they may arrive in an arbitrary order. These characteristics make the datagram APIs ideal for low-latency, best-effort data transmission. You can think of datagrams as user datagram protocol (UDP) messages, but encrypted and congestion-controlled.

Others:

There are other protocols that was not mentioned in this article which are less common but widely used in real world applications.

UDP: A transport layer protocol that is a great fit for streaming videos and communications where partial data loss is not very important.

WebRTC: similar to gRPC allows a RPC communication over HTTP.

Summary:

Many engineers believe that the latest technologies are the greatest and they need to be use to the current projects they are working on simply because it’s ‘cool’. Whilst I think using the latest technology is great, there are always some caveats and considerations when using technologies. As a good engineer, you need to always be aware of them and assess what’s a good solution to your problem.

So which protocol is the best to use for my next application?

While there are many different solutions to implement the communication layer, the answer remains dependent on your requirements and the timelines and goals. You can have a blend of different technologies in your implementation. For example, you can have a profile sign up API implemented using RestAPI and use WebSockets for chat function in your application.

My recommendations:

Currently, as a general rule to make it simple and ship your application quickly to the market, I suggest to start by considering Open API and Restful APIs. If time is not a concern, it’s worth implementing gRPC and designing .proto file specs to achieve great performance. In some platforms such as .NET core 3.1+, gRPC is a first class citizen and natively supported in Microsoft APIs.

If performance is a concern or part of your system has extensive number of clients and payloads are relatively large, you can consider gRPC to increase the performance.

If you have a lot of APIs and you think you are constantly adding new APIs related to querying and updating same entities, you can consider using GraphQL.

If you require to have a live communication in web or between a mobile clients, you can consider WebSockets.

If your application requires exchanging data reliably at a very high speed with a low latency, you can explore Socket programming.

If you have any questions, comments, suggestion please don’t hesitate to reach out! If you also found this article helpful please don’t forget to clap 👏 and share it with your friends! more cool articles are coming up, so stay tuned!

Helpful links:

https://www.cloudflare.com/learning/performance/http2-vs-http1.1/