Photo by Pavan Trikutam on Unsplash

“The single biggest problem in communication is the illusion that it has taken place.” ― George Bernard Shaw

Communication is a mandatory element of the software systems, the software system might running on different platforms on different servers and using different technology stacks. the set of definitions to communicate among the applications is called API (Application Programming Interface).

APIs sometimes can act as a contract, both the parties have to agree on the structure of the way they are going to communicate. It is not only purely communication because the APIs system now have the ability to integrate new components to the existing system or two different systems

Image from RedHat

Types of API

Public API - These APIs are exposed to third-party developers. these types of APIs can be free or subscription-based.

Private API - These APIs are only designed for inside the organization, private APIs are used for all the in-house application integration and developments. Though the application is available to the public API is always not.

Partner API - When two or more organizations are working together with an agreement the certain company will expose API endpoints with a certain amount of accessibility and control over the partner APIs. This is mostly done in application integration between companies.

Now let’s move on to the original topic of finding out the widely used API Specficications/Protocols are.

SOAP (Simple Object Acces Protocol)

SOAP(Simple Object Acces Protocol) is a messaging protocol, using XML for the message format, the important thing here when being a protocol is the specification rules should be followed when communicating. SOAP cannot break the constraints of its protocol. as a contract or guideline of how to communicate SOAP included the WSDL (Web Service Description Language) document with it. SOAP messages can transfer using HTTP or SMTP. However, the SOAP is not widely using now.

Sample SOAP request and Response (Image from ResearchGate)

REST (Representational State Transfer)

REST(Representational State Transfer) is the most popular specification at the time, and the main difference with the SOAP is that REST is an architectural style, which means there are no mandatory standards, API developer can change it according to his or her idea. However, the author of the REST has mentioned six constraints to comply to be a REST API.

1.Client-server architecture: REST architecture is composed of clients, servers, and resources, and it handles requests through HTTP.

2. Statelessness: No client content is stored on the server between requests. Information about the session state is, instead, held with the client.

3. Cacheability: Caching can eliminate the need for some client-server interactions.

4. Layered system: Client-server interactions can be mediated by additional layers. These layers could offer additional features like load balancing, shared caches, or security.

5. Code on demand (optional): Servers can extend the functionality of a client by transferring executable code.

6. Uniform interface: This constraint is core to the design of RESTful APIs and includes 4 facets:

  • Resource identification in requests: Resources are identified in requests and are separate from the representations returned to the client.
  • Resource manipulation through representations: Clients receive files that represent resources. These representations must have enough information to allow modification or deletion.
  • Self-descriptive messages: Each message returned to a client contains enough information to describe how the client should process the information.
  • Hypermedia as the engine of application state: After accessing a resource, the REST client should be able to discover through hyperlinks all other actions that are currently available.

Although the REST is meant to be asynchronous it is communicated through the HTTP/1.1 protocol, due to the limitation of the technology it does not work asynchronous manner, but Message Brokers are the solution for this.

Software Engineer