Communication Protocols

3.1.0 Introduction

In the exposure realm, one of the most common methodologies to build a communication structure between several system is to use a communication protocol. These protocols have evolved over the years from SOAP to REST to so many other communication protocols and principles that manifested their own technologies to accomplish exposing APIs to distributed systems.

In the .NET world, technology has evolved with the evolution of architecture from SOA with WCF to Microservices with REST. The evolution continues but the principles change less often. In these upcoming chapters we will be discussing the most common communication protocols with a standardized way to implementing them for an enterprise-level applications.

3.1.0.0 Principles & Rules

Communication protocols are required to accomplish two things when integrating with core business logic. Results communication and Error reporting. Let's talk about those briefly:

3.1.0.0.0 Results Communication

Any communication protocol is required to satisfy the principle of returning core business logic result. This result can be serialized into some unified language like JSON or simply be communicated as is. In the case of API libraries there is usually no need to serialize and deserialize data. But that comes with the limitation that only technologies that can integrate with these libraries can actually benefit from it.

Communicating results may also be encapsulated with a status of some kind. In the case of RESTful API communications a 200 code can accompany the returned serialized JSON result. These codes allow the consumers to understand the next course of action. Some 2xx results may require a delayed action if the response is just Accepted but not necessarily Created.

3.1.0.0.1 Error Reports

If the core business logic is expected to provide a detailed report of all the validation errors for instance that occurred in a particular request. It is the responsibility of the communication protocols to represent these error reports either in their original form as is, or serialize the report in a language that is easily deserializable and convertable back into the Exception original form on the client side.

Error reports shall also have their own codes in case they are serialized so the client knows what the next course of action is. It is highly recommend to follow a standardized way of communicating errors with documentation preferably to help guide consumers to develop the best clients for these APIs.

3.1.0.1 Common Types

Let's explore some of the most common types of communication protocols in this section.

3.1.0.1.0 REST

At the time of authoring this Standard, RESTful APIs are the most common form of communication between distributed systems. REST is a Representational state transfer protocol with certain constraints that specifically defines the form of communication, error reporting and its very stateless nature. RESTful APIs are technology agnostic. They can be implemented by any technology or a programming language but they allow these technologies to communicate with each other statelessly without any hard dependency on the server or the client choice of technology.

3.1.0.1.1 Libraries

The other most common communication protocol is APIs implemented within libraries. For instance, nuget packages are published and distributed libraries that allow developers to leverage a localized core business logic or communicate with an external resource to achieve a certain goal.

3.1.0.1.2 Other Types

There are several other types of communication protocols. Some of them are older and some others are about to present themselves in the software industry. These types are like SOAP with manifestations like WCF and gRPC, GraphQL and several other protocols.

We will be mainly focusing on RESTful APIs as a more common communication protocols with a brief touch on Libraries. And as we evolve and learn further so will our Standard which will include more and more different communication protocols and evolve in terms of patterns as well.

Let's get started with RESTful APIs as a communication protocol and dive deeper into the different aspect of that exposer component.