Overview:

Regardless of specialization, it’s inevitable that as a developer or project owner you will need to leverage an API at one point or another. 

An API is shorthand for Application Programming Interface. Although many types of API exist, the core focus of this article will be Web APIs in particular.

In the hyper-connected world we occupy, a large majority of data transfer happening every instant rely on various Web APIs. As the gatekeepers to data and actions on that data, it’s a crucial task that developers understand how to use existing Web APIs, but, how to create them.

In addition to the main three types of API, I’ve included a bonus for the more curious readers.

1. The SOAP API

SOAP, also known as Simple Object Access Protocol has become less popular over time. Given that the original specification was written in 1998, it is no longer considered the “sexy” approach to transferring data, however, it has stood the test of time and is still considered the gold standard by a handful of industries.

SOAP requests are regularly composed using XML and can be exchanged over a variety of protocols, not limited to: 

  • HTTP
  • SMTP
  • TCP

What does a SOAP message look like?

A SOAP message consists of four main parts: Envelope, Header, Body, and Fault. Of these, only the Envelope and and Body are required.

  • Envelope – As the name suggests, the Envelope is the set of XSL tags that surrounds the entire message
  • Header – This optional part of the message contains metadata that can be used to extend the contents of the body and provide extra information to the sender/receiver
  • Body – The main part of the message that is transmitted
  • Fault – Information about any errors that occurred while handling the Body will be stored here
<?xml version="1.0"?>
<soap:Envelope 
    xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
    xmlns:m="http://www.example.org">
  <soap:Header>
  </soap:Header>
  <soap:Body>
    <m:GetSomeData>
      <m:DataField>Sensor 123</m:DataField>
    </m:GetSomeData>
  </soap:Body>
</soap:Envelope>

Often, a SOAP message will be created by referencing a WSDL, which is also XML. In short, the Web Services Description Languages used with SOAP messages acts as an interface. This interface defines the usable data and actions available to the API; this specification creates a “contract” between the API and the message being sent/received.

Where is SOAP used today?

Some industries that require strict contracts and data security over flexibility in their APIs, these users still favor SOAP. A great example of a modern company that uses SOAP is PayPal.

For increased flexibility of data and ease of access, you may choose to investigate REST or RPC as an option for your API architecture.

2. The REST API

REST, stands for Representational State Transfer. Believe it or not, the origin of REST is nearly as old as SOAP, its first definition was in 2000. Over the last decade, the REST architecture has become one of the most popular ways for new APIs to be developed.

When interacting with a REST API the data access concepts revolve around the idea of a “Resource” that is expressed through a URL that may appear as an HTTP request. Although it appears similar, REST is NOT HTTP. To be considered a true REST API it must conform to the 6 guiding constraints. APIs developed with these constraints are called “RESTful”.

RESTful APIs do not require the use of XML or JSON, however, these are the two most common data formats used today – partly, because they are easily consumed by API users and can be cached by browsers.

What does RESTful data look like?

An example of a URL(s) which represents a the User resource and its Configuration resource may appear as the following. Notice that the resource path contains only nouns, the verb is implied by the type of request:

  • [POST] /user – create/update user
  • [GET] /user/{id} – fetch user by ID
  • [DELETE] /user/{id} – delete user by ID
  • [GET] /user/{id}/configuration/{id} – fetch configuration by user and id
{
	user: {
		id: 12345,
		name: Douglas
		email: douglas@xxxxxx.net
		configuration: {
			id: abc
			language: English
		
	}

}

Unlike SOAP messages, the data transferred while using the REST architecture does not have a formal structure. However, the API may require specific data to be present when interacting with the endpoints. Most often, the REST API architecture is used for basic CRUD functionality.

Where is REST used today?

From enterprise to hobby project, almost all modern software stacks contain a REST API that for accessing data. For a list of some of the most used public APIs check out this article from RapidAPI. To learn how to create a simple CRUD API using Spring Boot, see our other tutorials.

3. The RPC API

RPC stands for Remote Procedure call. This type of client-server interaction has been present in software applications since the 1970’s, however, the term “Remote Procedure Call” was not coined until 1981. 

It’s easy to confuse REST and RPC as they both have similar strategies for interaction. An RPC API is less predictable than the REST endpoints, however, the endpoints tend to be tailored to the clients use case. Even though RPC are not as predictable, they share the core principles of REST.

As the name suggests, Remote Procedure Call APIs are verb focused instead of noun focused. This means that the client is requesting a particular action be taken by the API – whereas the REST API is generally limited to CRUD operations. 

What does RPC data look like?

RPC APIs do not have a strict data type or format, they are commonly implemented using JSON or XML. As an example, an RPC API to interact with geolocation data might expose various ways to find data. The following URL might return a result set within the radius (miles) of a set of coordinates:

  • [GET] /points/getPointsWithinRadius?radius=2&lat=44.51&lon=-88.01
{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {
	“id”: “greenBay”
      },
      "geometry": {
        "type": "Point",
        "coordinates": [
          -88.02383422851562,
          44.50923820945519
        ]
      }
    }
  ]
}

Where is RPC used today?

RPC APIs tend to be more application specific as the commands are specific. Whereas a REST API being more generic might be used for a wider range of applications.

It’s a common practice that companies who expose REST APIs also expose endpoints with the RPC architecture in order to support functionality other than CRUD operations. Many of the APIs listed in this post by RapidAPI are RPC APIs or hybrid RPC/REST APIs.

Bonus: GraphQL API

GraphQL Logo and Link

GraphQL combines the concepts of a Graph Datasource with the straight-forward concepts of a Query Language. The first stable build of GraphQL was published by Facebook in 2018. GraphQL is not necessary a true type of API architecture, but, its design allows it to sit in the front of existing APIs as a proxy/façade. 

The core concept of GraphQL allows the client – such as mobile application or web app – to define the operation and more importantly, the structure of the data that is returned. 

Unlike all of the previous API URLs we’ve seen, GraphQL APIs use a single endpoint and supports both [GET] and [POST]. Note that GraphQL has a preference of application/json data:

  • [GET] /getData?{data{attribute1 attribute2}}
  • [POST] /getData
// POST /getData
{ data
    {
        attribute1
        attribute2
        attribute3
    }
}

One of the best features of GraphQL is that its implementation allows the API to aggregate data from the underlying REST, RPC or SOAP API. The net result is that a single request can be made by client instead of multiple requests  made from the client for the same result.

For more information on GraphQL and how it can be implemented, visit the official GraphQL website.