API Protocol types: When to use each with Examples
Tags: webdev, javascript, api, beginners
Published: 2023-09-27 18:28:19

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

1. **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
2. **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
3. **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
4. **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

1. **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

1. Strong Typing: SOAP has its own language called the WSDL which enforces strong typing, this reduces runtime error. Strong typing is preferred by corporations
2. 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
3. Enterprise level security: SOAP comes with built in security standard called the WS-security which enforces a robust set of security features such as encryption and authentication


## Cons of SOAP API

1. 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
2. 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

1. .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
2. 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
3. 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
4. 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 flexibility of client queries

### Pros of GraphQL

1. 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
2. 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
3. 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

1. 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
2. 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

1. **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
2. **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 received

### Pros of using gRPC

1. Speed: Because gRPC uses HTTP/2 standard and protocol buffers which google invented the APIs are super fast
2. 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
3. Strong Typing: gRPC is a strongly typed language which reduces bugs and increases reliability of the code

### Cons of using gRPCS

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


### Practical Applications and use cases

1. Microservices and communications
2. Data Streaming
3. 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

1. 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
2. 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
3. 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

1. 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
2. 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

1. Chat, Voice and Video Calling
2. Real Time Dashboards
3. Financial Trading platforms
4. Interactive online games


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/uizte6i6t41rr3o50bud.png)

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

## 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