API has been used so much these days for virtually every software development process, and it has been the talk of the day for quite some time. To be able to grasp what it is, and how to choose a web protocol, here are some key explanations and points.
Application programming interfaces (APIs) are an essential part of software development since it’s APIs that are responsible for interactions among apps, databases, and components.
What types of APIs are there?
- Web Service APIs
- WebSocket APIs
- Library-based APIs
- Class-based APIs
Today, we’ll be looking into the architecture and foundations of web service APIs. There are a few different approaches to implementing web APIs:
- XML/JSON RPC
- SOAP
- REST
- GraphQL
To make sure everyone’s on the same page before we start talking about these in detail, let’s brush up on our terminology.
RPC (Remote Procedure Call) – a technology that allows you to call methods that are stored on another computer on another network without having to understand that network’s details.
XML RPC – a protocol that was released in 1999, XML is used to encode its calls and HTTP is used as the transport mechanism. Below, you can see some examples of requests and responses:
Host: betty.userland.com
Content-Type: text/xml
Content-length: 181
<?xml version="1.0"?>
<methodCall>
<methodName>examples.getStateName</methodName>
<params>
<param>
<value><i4>41</i4></value>
</param>
</params>
</methodCall>
HTTP/1.1 200 OK
Connection: close
Content-Length: 158
Content-Type: text/xml
Date: Fri, 17 Jul 1998 19:55:08 GMT
Server: UserLand Frontier/5.1.2-WinNT
<?xml version="1.0"?>
<methodResponse>
<params>
<param>
<value><string>South Dakota</string></value>
</param>
</params>
</methodResponse>
JSON RPC was released in 2009, and it’s not difficult to guess the main difference between the previous protocol and this one – only that JSON is used as the format for data encoding.
SOAP (Simple Object Access Protocol)– a lightweight, XML-based protocol released by Microsoft in 1998 for exchanging information in decentralized, distributed environments. The primary goal of this protocol was to implement RPC.
REST (Representational State Transfer) – a relatively simple approach introduced in 2000 by one of the creators of HTTP, REST isn’t a protocol or standard but rather an approach to creating APIs. REST is used as an alternative to RPC.
Comparison of protocols
SOAP
When SOAP was introduced, it was a revolution in software and web app development. But the protocol received a lot of criticism because of the difficulties of its approach. Nevertheless, SOAP developed over time, and SOAP 1.2 was recognized as a recommended protocol in 2003.
SOAP’s main principles:
- Uses XML for coding data
- Uses the majority of common protocols (TCP, UDP, HTTP, SMTP, FTP)
- Uses two methods for HTTP transfers – GET and POST. GET is used to receive data; POST is used in all other situations.
SOAP works best of all when there’s communication between different platforms that have tools to speed up the development.
REST displays data in the most convenient format for the client. The main idea behind the REST approach is that each time the service is addressed, the client app changes its state.
REST’s main principles:
- Client-server architecture
- Each resource has its own ID
- Resources may be connected to an ID
- The server doesn’t save sessions in memory, which makes scaling simple
- Uses standard HTTP methods
The biggest advantages of REST are that it’s easy to use, supports the HTTP protocol with standard error codes, and is popular among developers.
SOAP or REST?
SOAP and REST can’t be directly compared because they perform different functions and should be chosen based on the particular task.
When you should use REST:
- When your service is JavaScript-based. JavaScript works with JSON.
- When your API is supposed to handle a high load, for example, Facebook’s and Twitter’s APIs need to withstand serious load testing.
When you should use SOAP:
- When interacting with platforms that have development acceleration tools that use SOAP, and therefore SOAP is supported.
GraphQL
GraphQL describes how data is retrieved from the server. In simple terms, you can say that GraphQL is a language that describes data that’s available to an API.
GraphQL was developed by a Facebook developer whose team realized that the REST API was facing some limitations. To understand the nature of these limitations, let’s take a look at a task that a lot of developers who create APIs have to deal with on a daily basis: retrieving a list of A objects (for example, a list of users or articles) wherewith each A object there comes a list of B objects (for example, a list of comments on articles or a list of users who have liked a particular post). Loading this additional data results in slower app performance for those requests where data associated with B objects become excessive.
You can resolve this issue by properly setting up work with the API response. Instead of doing this, however, some developers prefer creating two separate requests.
Now let’s look at a more complicated situation. Let’s imagine that A objects are stored in PostgreSQL, whereas B objects are stored in Redis. If that’s the case, we need to retrieve data from two different sources. Considering how many types of data an app like Facebook has to process at the same time, it’s understandable that they wanted an alternative to the REST API.
GraphQL allows clients to describe which data they can receive from a server, and data can be successfully retrieved from several sources. GraphQL allows developers to describe necessary data with the help of types.
When to use GraphQL:
- When you need to reduce the number of requests for data sent to the API.
- When the dependency between the client app and the server disappears, as the client app decides which data it needs and in which format that data should be requested.
Overall
As you can see, these protocols are optimal for different contexts, and choosing the best option depends on your particular project and is ultimately up to your developers.