In our previous post, we discussed about APIs. We shall dig deeper into it in this post and read about  classification and types of APIs . Such has been the trend that whenever we think of HTTP APIS we think of REST API. However, that is not the case. REST APIs are just a subset of HTTP APIs. HTTP APIs are any APIs that communicate over the HyperText Type Protocol.
Any HTTP Request is made up of two parts:

  1. HTTP verb (Method)
  2. Resource (Endpoint)
HTTP VERBS:

You must have seen GET, POST, etc prefixed with an API call. Well, they are the verbs or methods. Each verb has a meaning or is coupled with a particular action that the endpoint should take. Each verb has some or other properties, which they may or may not have:

  • Have a meaning
  • Idempotent or not (A request method is considered “idempotent” if the intended effect on the server of multiple identical requests with that method is the same as the effect for a single such request)
  • Safe or not (Request methods are considered “safe” if their defined semantics are essentially read-only)
  • Cacheable or not

 

 

 

Idempotency can get a little confusing so I will elaborate it here a bit. Suppose you issue a GET request to read a particular data, now irrespective of the attempt number you will get back the same data and the server will be in the same state (given there is no changes done to it by any other request). Thus Get is idempotent. Also while using a DELETE verb like DELETE /items/15, it will delete the item with ID 15 for the first time and on the next attempts it won’t find any item with ID 15 and thus won’t do any changes to the state of the system, making it Idempotent.

 

Now we know all about an HTTP API, let’s get to know the different types of  APIs.

Remote Procedure Call (RPC):

RPC is the oldest and simplest form of API interaction. It is as simple as calling a function that is written in another server (another host machine).  This when implemented on HTTP models a Web API. The concept is as simple as passing arguments and calling a function hosted in a separate machine. The arguments are passed in URL and the other machine (which executes the procedure) maps every incoming endpoint to a particular function.
This is precisely similar to executing a function in java, just with two different, the function is hosted on a separate machine and you call the function via WEB URL.

//Sample HTTP RPC Request

POST /getTermRequest HTTP1.1/
HOST: example.com
Content-Type : application/JSON

{ "term" : "Example" }

In the example, we used JSON to pass data to and from the remote procedure. We can use different strategies as well like XML. Thus RPC can be further classified into

  • XML-RPC
  • JSON-RPC
  • SOAP

XML-RPC has a problem with data types.  Everything in an XML is a string, thus differentiating between int and string became troublesome. JSON-RPC reduced the problem but still, the difference between an int and decimal was an issue. Both XML-RPC and JSON-RPC are not widely used now but thanks to some corporates like Salesforce, SOAP is alive and kicking.
We will discuss SOAP in detail.

 

SOAP:

SOAP stands for Simple Access Object Protocol. SOAP is like XML-RPC but it is accompanied by a Web Services Description Language (WSDL).  Think of it as metadata which describes which data is of which data type. The parties (client and server) agree upon a WSDL format, and then when actual XML arrives, the data is parsed to the data types defined in WSDL.
Let’s look at an example of a WSDL file.

<message name="getTermRequest">
    <part name="term" type="xs:string"/>
</message>

This file means that the input message has a name getTermRequest and the request contains one element term of type string. Any XML to this endpoint will have a variable term in which the receiver will parse a string. Here is a sample SOAP request payload.

<?xml version="1.0"?>

<soap:Envelope
xmlns:soap="http://www.w3.org/2003/05/soap-envelope/"
soap:encodingStyle="http://www.w3.org/2003/05/soap-encoding">

<soap:Body>
  <m:getTermRequest xmlns:m="https://www.example.com">
    <m:Term>Example</m:Term>
  </m:getTermRequest>
</soap:Body>

</soap:Envelope>

 
As you see in the payload, the only piece of information required was <m:Term>Example</m:Term>. This is a con of SOAP, we need to send huge payloads even for sending very small data. Also if any change is to be needed in the API request/response format, the WSDL file has to be changed at both the ends. But still, SOAP is a popular way of making HTTP APIs even today.

REST:

Rest is a paradigm proposed in 2000 where server-side data is made available through request data in very simple formats like JSON, XML or even a normal text.  The biggest difference between RPC and REST is that for REST everything is a resource.  REST utilizes the true meaning of HTTP verbs and calls the resources as nouns. Most of the action in REST are represented as basic CRUD operations on resources. Let’s have a look at our RPC example, 
We used getTermRequest which is an action, a similar request in REST will translate to:

GET /Term HTTP1.1/ 
HOST: example.com 
Content-Type : application/JSON
 { "term" : "Example" }
 

Here Term is used as a resource while in RPC it was used as an action. The same resource can be used with DELETE or PUT to provide for other actions. That is not much of a difference, but conceptually this is what separates RPC from REST.  One more difference is statelessness. A REST API has to be stateless, which means the server does not maintain any kind of state or any kind of relation from the previous API requests. Let’s take an example of social media accounts, in RPC the server might maintain a session pertaining to every user that is logged in, but in REST no session is maintained on the server-side. In REST user first obtains a token by hitting the login API and then appends the token to every subsequent request to tell the server that the user is authenticated.

So we find RPC is better to use when we have a smaller use case and want to specifically a particular thing, whereas REST is useful when all CRUD operations are needed to be done on a resource. There is no general rule as to which style is used under what condition, but a simple rule of thumb says:

  • If your API has to do an action, go for RPC.
  • If your API has to Create/Update or Delete a resource go with REST.