Demystifying Web APIs: A Clear-Cut Guide to Types, Features, and Comparisons

An Application Programming Interface (API) provides a medium that creates connection between computers or between computer programs. It is a types of software interface, offering  a service to other piece of software. While there are numerous types, protocols and technology involved, the main purpose of APIs is always to allow one piece of software communicate with another.

Web APIs is a programming interface/ application type that provides communication or interaction between software applications. Web API is often used to provide an interface for websites and client applications to have data access. Web APIs can be used to access data from a database and save back to the database.

An Application Programming Interface API comes in difference forms, when developer get down to build web API first they decide which specification to used. In this article, we are going to compare the four (4) major web API that support communication between clients and servers.

The four major web API types that we are comparing are

1. Remote Procedure Call (RPC)
2. Simple Object Access Protocol (SOAP)
3. REpresentational State Transfer (REST)
4. Graph Query Language (GraphQL)

1. REMOTE PROCEDURE CALL (RPC)

PRC is the earliest and the simplest type of API. The name speaks for itself as it a straight forward interaction with a local client since connect to a remote server.

How does its works.

Both clients send an application and the server used different call parameter,  So, the must be converted to be  understand on the other sides. This parameter conversion is performed by a dedicated PC short code called STUB. So when a client calls a server by a RPC API a client STUB converts the parameters used to a function call then server STUB  deconvert them on it side and execute the function. After that server STUB then reconvert them back for the client and the client STUB then deconvert them. The RPC pattern has been around since the 80s and it started with XML and later JSON based version.

In 2016, google came up with a general purpose RPC called gRPC, a high performance, open source universal RPC framework. Today, massive systems like Facebook, Apache Thrift and twirp uses nothing but gRPC for the internal microservices communication. As microservices exchange tons of calls per day, it is a really high performance API to optimize the network layers and the RPC style with a short language messages goes easy on the network.

2. SIMPLE OBJECT ACCESS PROTOCOL (SOAP)

In 1999, Microsoft scraped XML-RPC with SOAP. XML-RPC  as it is called, it has to do with XML itself. It did not distinguished between different data types so the developers had to add an additional meta data to label a field with the data type.

SOAP APIs It is a messaging protocol for exchanging structured information in the implementation of web services in computer network.

It used an XML-based messaging protocol which includes the Envelop a root element of every SOAP message starting it and ending it. Then follows Header, an optional sub-element. A header filled up with any application relativity service or extra requirements necessary for the message processing. And now the Body which contains the request or response to the recipient and when the processing failed, the response will also includes the failed element describing an error that occurred.

Although, many developers shadow idea of  having to deal with the the soap API yet we cant ignore it. SOAP is still taking around for a larges finest services and couple of systems like salesforce that is because of it security. WS-SECURITY extension encrypt a message and put a lock on it and only a recipient with the security token is able to pass authentication access  the body.

SOAP also provide a chained messages to keep the server aware of the previous request.  Storing other received information thus heavy on the server but it is necessary for couple of transaction where multiple parties are involved.

In 2000, the web started changes. It requires a light weight, uniform and a flexible way for system and services to communicate but SOAP losses with XML structure and inflexibility.

3. REPRESENTATIONAL STATE TRANSFER (REST)

The Representational State Transfer REST surfaced to handled the new requirement of web and for sometimes it was used in parallel with SOAP but soon REST won the popularity contest.

The RESTful approach drastically differ from SAOP:

1. It is resource state – RPC/SOAP used different command to manipulate the servers like SendUserMessage, GetUnits, DeleteUser, LocateVihecle, addEntry, etc while REST focuses on resources, actual data but they keep both to s minimum using HTTP method GET, POST, PUT, DELETE and it is much easier than using numerous method required to operate SOAP and RPC APIs.
2. Instead of fixed and rigid structure of SOAP, REST suggests constraints that must not be crossed such as
   1. Uniform interface constraint
   2. Client-server autonomy constraint
   3. Stateless constraint
   4. Cacheable constraint
   5. Layered system constraint
   6. Code on demand constraint

4. GRAPHIC QUERY LANGUAGE (GraphQL)

in 2015 Facebook get tired of the rest over fetching data and they came out with the new API syntax called GraphQL. In contrast to REST, GraphQL make a single precise request that returns and all suitable files.

In REST there are a lot of end points and they return some fakes data, so the client has to make some merging of end points to eventually get the information that was request but in GraphQL client can customize end-point. How do they mange that?.

GraphQL is using SCHEMA to customize end-point. It provide the client with

1. data description
2. how the data is structure on the server
3. Available resources and relationship  between them
4. Fields each resource includes

This way the client know how to formulate the query and ask the server no more. Talking of learning curve, REST can be learned in two days but the learning curve for GraphQL is step by step one need to prepare the cover time for figuring out GraphQL niche operation and Schema Definition Language (SDL). While GraphQL has a desire for long term project, small and medium once do not need to border and can follow know path of the REST.

In conclusion, Today, you may hear someone referring to REST as Rest in Peace and cheer for GraphQL whereas ten years ago it was a reverse story when REST been the king and SOAP was junk yet we see some projects were still in need of it. Sometime API provider offers two types of APIs in parallel for example, integrating kind of post services, online store can choose between REST and SOAP architecture. So, do not give in the labeling API design but always keeps in mind the need of your software because they will determine your choice.