API Protocol types: When to use each with Examples

API or application programming interface are a way through which software communicate with each other.

The software does this by using a set of defination and protocols that are defined by the software maker to enable the user or another software to control the given software

API can be used for communicate between parts of a single software or between completely different softwares altogether

Given the importance of APIs in real life, it is important to choose the right protocol for their implementation. The choice of which API protocol to use in your software could lead to difference in

Performance
Scalability
Security and
User Experience

In this article we will learn about the different API protocols available, how to use them and when to use each protocol with examples

HTTP/REST Protocol APIs

REST API is the most common type of API used in the world today. REST stands for Representational State Transfer. The REST API has functions like

GET: used to get data from the server or a resource
POST: used to post data on to the server or another software
PUT: used to update an already existing data on the server
DELETE: used to deleted data from the server

The REST api uses the HTTP methods to communicate with other software or the remote server

The REST APIs are stateless, meaning the server does not save any client data between the requests.

JSON data format

JSON or the JavaScript Object Notation in REST APIs has become the de facto data format for RESTful APIs

It is easy to read, lightweight and quick to parse with built in JavaScript function JSON.parse It is important to note that the REST itself does not prescibe a format but JSON has become a preferred format

Pros of REST API

Speed: The REST API is very quick and requires very less bandwidth to work. This is because it uses the HTTP protocol to transmit the data and hence REST API is the Gold Standard in API communication
Used Everywhere: REST APIs are ubiquitous, so much so that at the mention of API people assume that it is going to be REST API and not of any other kind. Approx 90% of all applications run on REST APIs
Ease of use: REST is very easy to use and almost all developers have used in their lifetime, so everyone is familier with REST APIs
Statelessness: REST API is stateless which means it does not require any data about the client that is calling the API to function

Cons of using REST APIs

Real Time Communication constraints: REST API cannot perform real time to and from communication from the client to the server. This is primarily required in real time communication platforms such as chat, video calling and audio calling. For this a seprate set of API called the websocket API are used

Practical Example using REST API in the real world

SOAP API

SOAP or Simple Object Access Protocol is an older protocol for building web services. SOAP was released before REST API came into existence

It is still a good API to use if you are building web services, if you compare it with REST API.

The REST API has a more arhitectural style as compared to SOAP API which has a well defined specification and is rules based.

There are a set of comprehensive rules and features that makes the SOAP API. The benefit of this is

SOAP is robust
Well defined
Secure and
ACID compliant

API specification

Protocol with contracts

The SOAP API has strict contracts between the service provider and the consumer of the API.

The language used to define this contract is called WDSL Web service description Language

The language defined the different aspects of the API such as

what the web service does
the type of messages it can recieve
how to structure those messages

Pros of SOAP API

Strong Typing: SOAP has its own language called the WSDL which enforces strong typing, this reduces runtime error. Strong typing is preferred by corporations
ACID Compliant: SOAP supports the ACID standard, this makes it a strong choice for transactions where integrity is very important such as in financial and healthcare scenarios
Enterprise level security: SOAP comes with built in security standdard called the WS-security which enforces a roburst set of security features such as encryption and authentication

Cons of SOAP API

Too much detailed: It is tool much detailed. The XML based language is hard to write and increases the size of each request as well as response. Which is a bother for both the developer designing the request as well as the machine parsing the response
Steep learning curve: With so much features and strong typing and protocols there is a steep learning curve when using the SOAP API and with 90% of the world using the REST API it is not worth it for the developers to spend time and energy learning SOAP API standard

Practical example of using SOAP API

.NET framework: The .Net framework was released in the 90s and as such offers support for building SOAP APIs through a dedicated toolkit which allows for easy WDSL contracts generation with a few clicks of the keyboard
Java Based JAX-WS: Many legacy systems are built on the Java Platform and as such the Java API for XML web services does provide a tool kit for building SOAP APIS
EDI over SOAP: EDI or the electronic data interchange transactions that are used in the supply chain management often work on the SOAP APIs. This is because the confidentiality, reliability and integrity of the transaction is quite important
Financial transaction with SOAP: In the financial sector the ACID compliance is often an requirement by the financial institutions that require the API and as such SOAP APIs are used there because they meet the compliance requirement

GraphQL API

GraphQL is a API released by Meta Platoforms also called facebook in 2015 as an alternative to REST API

REST exposes multiple endpoints for different resources such as /users for users /media for images and video etc but the GraphQL exposes a single endpoint for all interactions

This allows the client to specify exactly what is wants and the API returns just that. This client driven approach is more efficient than the REST API because it does not return unnecessary data

Query Language and Runtime

The GraphQL servers both as a query language and a runtime for your API as well

The language part of the GraphQL let you know how to structure the request for the API and the runtime part involves how to fulfill the said request

GrapQL has a schema definition that forms a contract between the client and the server, decribing the types of services and requests the client is allowed to perform or request

The Schema defines the types and the fields on those types, then it also specifies what functions can be called on each field. This makes the GraphQL somewhat like SOAP but with the flixibility of client queries

Pros of GraphQL

Flexible Queries: With GraphQL the client can fetch exactly the data which the client needs, this makes the API calls more efficient and fast because it reduces the payload that is being transferred
No Over fetching as compared to REST API: In the REST API when the client calls an endpoint the API provides the whole set of data. Which might or might not be fully used by the client that is calling the API. Thus in REST there is overfetching of data
Strongly typed Schema: GraphQL like SOAP APIs provide a clear contract between the client requesting the data and the server and is thus strongly typed which reduces bugs and run time errors

Cons of GraphQL

Steep learning curve: because GraphQL is strongly typed and creates a clear contract between the client and the server, it requires its own query language, resolver functions and other GraphQL specific concepts to be learned which could be a turn off for many developers
Query Complexity: The flexibility of client asking for specific data from the server can lead to a requirement of creating quite complex queries which could be burden for the developers and as such act as more of a problem than as solution.

Examples of using GraphQL in real life

Facebook
twitter
Shopify
Netflix
Github

gRPC Framework and API

gRPC also called as a remote procedure calls is a go-framework for microservices. It has been developed by Google and uses the HTTP/2 protocol as its Interface definition language

Its main features are

Performance
Strong typing
Cross-Language Support
efficient

gRPC is designed to enable different services to talk to each other both in a point-to-point manner such as client / server or even work in distributed environments

Basics of gRPC

HTTP/2 : The gRPC uses the HTTP/2 transport layer to transmit the data. This layers offers features like multiplexing, header compression and offers low latency and high throughput performance. Thus gPRC offers low latency and high performance
Protocol Buffers : The framework uses the Google protocol buffers as its IDL language. This helps document the API as you are building it and specifies what data will be sent as well as recieved

Pros of using gRPC

Speed: Because gRPC uses HTTP/2 standard and protocol buffers which google invented the APIs are super fast
Streaming Support: gRPCs have strong streaming support which helps with more advanced use cases such as live video streaming, chat, audio and video calling etc This is something is difficult to achieve with REST APIs
Strong Typing: gRPC is a strongly typed language which reduces bugs and increases reliability of the code

Cons of using gRPCS

Dependent of HTTP/2 which is not widely supported: Older infratructure does not support the HTTP/2 protocol and hence it could be difficult to use the gRPC API there
Protocol buffers requirement: Most developers are familier with the REST APIs and they use the JSON format with the REST APIs. Developers are not familier with protocol buffers which is something that is new and invented by Google.

Practical Applications and use cases

Microservices and communications
Data Streaming
Remote Procedure calls

Websocket APIs

Websocket API protocol is designed for real time communication, that is full duplex and it is over a single long lived connection.

Websockets are an upgrade over the HTTP protocol, because unlike HTTP websockets can and do offer to and fro traffic both from the client and the server

Here are some of the features of the Websocket API

Pros of Websocket API

Real Time and full duplex connection: Websockets provide an essential feature that is not provided by the REST APIs and that is real time communication and full duplex connection. This is very useful in creating real time services such as chat, Voice and video calling etc
Single Connection: Websockets initially set up an handshake through the standard HTTP or HTTPS connection. After the handshake is done the protocol switches to a single connection through websockets
Reduced latency: Because there is no need to open a new connection and all the data is transferred through an already open single connection the latency is very low with the websocket connection

Cons of Websocket API

Complexity: REST API are stateless and very easy to learn and setup. Websockets through easy but are a bit difficult to learn as compared to the REST API. Websockets are a newer concept as well as compared to REST API so developers need to wrap their heads around it and learn how the Websockets API work
Resource Intensive: Because the connection is kept open the Websocket are bit more resource intensive than the REST APIs which closes the connection once the transaction is complete. Websockets also take a toll on the server when there are a lot of clients with open connections to the server. The server has to maintain all the connections hence it is resource intensive.

Real World Applications

Chat, Voice and Video Calling
Real Time Dashboards
Financial Trading platforms
Interactive online games

Need Chat API for your website or app

DeadSimpleChat is an Chat API provider

Add Scalable Chat to your app in minutes
10 Million Online Concurrent users
99.999% Uptime
Moderation features
1-1 Chat
Group Chat
Fully Customizable
Chat API and SDK
Pre-Built Chat

You might be interested in some of our articles:

Conclusion

In this article we learned about various types of API protocols and when to use each protocol along with real worl use cases and examples for each

I hope you liked the article and thank you for reading