Types of APIs

API (application programming interface) is a piece of software that communicates a client with the services and the data of another, i. e., the APIs allows the communication between two pieces of software.

Nowadays, when someone wants to build an API, generally it is developed as a REST API. But there are other approaches that can fit better with your product.

We are going to see the difference types of APIs based on the protocol and the type of data that it is used to communicate.

• REST
• RPC
• SOAP

 

REST

REST (Representational State Transfer) is a type of architecture of web development that is based on the HTTP standard.

There are some requisites that a REST API must accomplish:

• It is stateless, i.e. it does not save state between requests.
• Correct use of URIs (uniform resource identifier).
• Correct use of HTTP
• Hypermedia

   

Correct use of URIs

URIs allow us to uniquely identify a resource that we want to get, modify or delete.

There are a basic rules to set the name of the URI of a resource:

• The names must not imply an action, they should not contain verbs. Example of incorrect URI: /user/4/edit. Example correct URI: /user/4 and what we want to do will be indicated with the HTTP method as we will see later.
• They should be unique, we should not have more than one URI to identify the same resource.
• They should be independent of the format of the resource.
  Example of incorrect URI: /user/4.pdf.
• They should maintain a logic hierarchy.
  Example incorrect URI: /user/4//1.

  Example correct URI: /organization/1/user/4
• The filters are not done in the URI.
  Example incorrect URI: /users/orden/desc and a correct one: /users?order=DESC

Correct use of HTTP

• Use the HTTP methods to indicate which action do we want to do with the resource.
  • GET: to read resources.
  • POST: to create resources.
  • PUT: to edit resources.
  • DELETE: to remove resources.
  • PATCH: to edit an specific part of a resource.

• Use the native code of HTTP (200,204,409,404…) when sending the response of a request
  • Example of an incorrect response:

    Status Code 200
     Content:{
       success: false,
       code:    734,
       error:   "not enough data"
     }

  • Example correct response:

    Status Code 400
     Content:{
       message: "Invalid id" }

• Types and format of the content.

  REST is very flexible and allows to send nearly any kind of data defining it in the Headers, such as XML, JSON, binaries, text… However, the type of the data normally use is JSON or XML.
  In REST API generally JSON is used, one of the reason is because it is easy interpreted by javaScript.

Hypermedia

Means to link the client application with the APIs, preventing this client to care about the access of the resources. i.e. when we return a list of user, we will indicate the URI to access to one of them.

 

RPC

RPC (remote procedure call) is a protocol that exposes methods to manipulate data through HTTP protocol.

In RPC, the endpoints can contain verbs to explain the actions that they make. This is something not allow in REST, that only has the entities and the actions is represented by the HTTP methods, as we see above.

In RPC, only GET and POST are used: GET when getting the information without modifying it and POST for all the other calls.

The type of data that is used can be XML (and then we are talking about XML-RPC) or JSON (and then we are talking about JSON-RPC).

 

 

SOAP

SOAP (Simple Object Access Protocol) is a standard protocol which defines how two objects in different processes can communicate by exchanging data in XML. In contrast with REST, this protocol does not allow us to use other type of data.

SOAP service, generally, use HTTP as transport protocol, which is very common when implementing Web Services. But SOAP is agnostic to the transport protocol and can send data using  FTP, POP3, TCP, SMTP. JMS, MQ…

As we have seen, XML-RPC y SOAP are very similar, for instance both send the data in XML. We could say the XML-RPC is a subset of the SOAP functionality.  

XML-RPC only use HTTP request while SOAP normally use HTTP/S but can use another transport protocol, as we have seen above.

 

 

Examples of use

To clarify concepts, let’s see an example of an endpoint in a API SOAP (JSON-RPC)  and REST.

JSON-RPC example:

POST /SendUserNotification 
{"userId": 1, "message": "This is a RPC API!"}

 

In the REST example, we can see that the resources we are manipulating are in the URL of the call:

POST /users/1/messages  
{"message": "This is a REST API!!"

In REST, we should be able to count on the fact that if we make this request GET:

GET /users/1/messages

All the messages that the user has received should be returned.

 

 

Then, when should we use SOAP and when REST?

If we want to model the domain, i.e. modify the resources (CRUD) then REST is a good option.

But, if we need to make different actions difficult to distinguish using the HTTP method, RPC is the best option.

Let’s see an example to understand it better. Imagine an app which has conversations. These conversations need to be started, finished, interrupted or cancelled. This actions are difficult to implement using an API REST. In this case, we should use an API based on  SOAP or RPC.

 

Do you know which approach are you going to use to develop your API?

 

 

Related links

QUIC: what hides behind HTTP/3

Automatize an API using Postman