Have you ever considered how many different types of APIs there are? API types usually refer to access types (open, partner, private, and public) or to design patterns (RPC, REST, SOAP, and GraphQL, for example).
In this post, we will address APIs in terms of design patterns since that's how our customers usually think of APIs when developing integrations for them (or when building the APIs themselves).
But first, let's start with the basics.
What is an API?
An API (application programming interface) allows apps to communicate with each other. The API controls access to an underlying system or subsystem. Much like a UI (user interface) allows a human user to interact with an app via a screen, keyboard, or another input device, an API enables other software to interact with an application.
For example, an API might connect an app's front end (user interface and business logic) and the back end (database). Another API might connect various subsystems within a single application, such as the contract subsystem to the organization subsystem.
Yet another API might enable data exchange with integration partners' apps. In this example, the API is an integration's connection point to access the underlying app and its data. APIs used for integrations are not the only available APIs but the ones our customers (SaaS teams that need to connect their apps to the other apps their customers use) need to work with daily.
How do APIs work?
We can think of the API as a door to the database. That door has security (restrictions on who/what can access the doorway), permits only certain types of data to enter or exit, and otherwise protects everything behind the door.
Some APIs permit data to be read from the underlying database (read-only access), while others allow new information to be written (write access). Other APIs support both reading and writing data. In addition, each API has a set of rules or constraints built into it regarding exactly what data is accessible via the API. Very few APIs expose all the underlying data.
To access data via an API, we send a request to the API, commonly a GET request. This request needs to match an API-defined structure and format. The request must also conform to any other rules imposed by the API. For example, the underlying database may have employee data, but the API does not allow any access to that data. As a result, sending a GET request for employee data via the API does not work.
Similarly, we send another request when we submit data via an API. This is often a POST request. Again, this request must match an API-defined structure, format, and other data rules. For example, the underlying database may accept the creation of new employee records but may not allow them to be updated if they already exist. In this case, sending a POST request to update an existing employee record will return an error.
What is an API protocol?
APIs are sometimes referred to by protocol, but this can be misleading because while some APIs have a name in common with a protocol (example: SOAP), others are not tied to a single protocol. As a result, we will discuss common integration APIs by design patterns to be more accurate.
What types of API design patterns do we see used for SaaS integrations?
If we could know all the APIs used for every integration with a SaaS app, there would be dozens or even scores of different API design patterns. Some companies have even built custom APIs which use unique design patterns. In other cases, some APIs have been around for many years and are still in use, despite substantial shifts in technology. We will focus on the APIs we often see used for building integrations with SaaS apps. These are:
- RPC APIs
- SOAP APIs
- REST APIs
- GraphQL APIs
Let's look at each of these in turn.
RPC APIs
RPC (remote procedure call) APIs are our shortlist's oldest type of APIs, having been around since the late 1970s. As a result, RPC APIs pre-date web development by a considerable margin.
Classic RPC APIs follow standard programming conventions since calling remote procedures uses a similar syntax to calling a local procedure from a programming library. As a result, when devs who are comfortable with common programming languages start thinking about APIs, they may gravitate toward an RPC design pattern because it has a baked-in level of familiarity.
Descendants of the classic RPC API are still viable with today's technology. And, if you are looking for a very efficient way to pass data back and forth, RPC can be the way to go. Classic RPC data is encoded in binary formats, and the RPC design pattern lends itself to brief messages. gRPC API, for example, takes advantage of the efficiencies of binary encoded messaging.
Other modern RPC APIs (commonly seen in SaaS integrations) generally use XML or JSON for the messages and transmit them via HTTP. These APIs are known as XML-RPC and JSON-RPC.
SOAP APIs
SOAP (simple object access protocol) APIs were first developed in the late 1990s for businesses to use for data transport on corporate networks. SOAP is an actual protocol for the exchange of data between apps. However, SOAP APIs add a layer of structure and complexity to SOAP. Though we are giving it a separate section, some consider SOAP APIs to be a sub-type of RPC API.
SOAP APIs often use HTTP/HTTPS as the transfer protocol, but they are not restricted to those protocols. They can use TCP (transmission control protocol), SMTP (simple mail transfer protocol), FTP (file transfer protocol), UDP (user datagram protocol), and just about any other protocol that supports text data exchange.
SOAP APIs use XML exclusively for messaging. And, as with RPC APIs, these APIs are best suited for sending brief messages. SOAP provides guidance for message request and response structures in addition to the message content and encoding.
Despite its strictness, SOAP is extensible. As a result, it has continued to evolve with developments in web applications. And with a focus on message security and automation, SOAP APIs continue to meet a need in the market, despite losing ground to newer upstarts such as REST APIs.
REST APIs
When it comes to APIs for web apps, REST (representational state transfer) is the leading design pattern. REST came about in 2000 because the burgeoning web needed a standard that would allow any server on the web to talk to any other server on the web. The team that developed REST believed that existing API design patterns, especially SOAP, were unnecessarily difficult for developers.
Unlike SOAP and RPC APIs, REST APIs are simpler to implement and easier to work with. This simplicity has led to massive adoption of REST APIs within the web ecosystem since the overhead of standing up a REST API is manageable by even the smallest dev teams.
REST APIs take the architecture that has worked well for the web and apply it to web services. Or, to put it another way, REST is designed to take advantage of the HTTP-based nature of the web. Like other APIs, REST APIs can use multiple transport formats/languages. JSON, XML, and HTML are popular, with JSON being the most common.
There are more REST APIs available today via the web than any other type. However, not every REST API identified as such accurately follows the REST design pattern, leading to APIs that should properly be described as "REST-like" instead of REST.
GraphQL APIs
GraphQL APIs are only a few years old, making GraphQL the newest design pattern/architecture on our list. It grew out of dissatisfaction with some of the limitations of the then-popular REST APIs. Among other things, REST APIs tend to have quite a bit of back-and-forth traffic because of multiple requests, and they don't support recursion well.
To address these issues, the team behind GraphQL stopped thinking about datasets as tables and started thinking about them as object graphs (from which we get the name for the query language and the resulting design pattern). As a result, GraphQL APIs are handy when developers need to retrieve structured, recursive data from a single server request.
Since it was made available for general use, many organizations have built GraphQL APIs for SaaS apps. Like REST APIs (and most RPC API implementations), GraphQL APIs use HTTP/HTTPS as the message transport mechanism. And as there is a growing need for APIs to support big data, GraphQL APIs are particularly well suited to handling large and complex queries and only returning the desired data.
As with any type of API, GraphQL APIs have their limitations. And, in some ways, GraphQL isn't doing something remarkably different from what might work for an RPC or REST API, but what it does, it does very efficiently. That's one of the main reasons we chose GraphQL for our dev API.
Does the API type make a difference?
With experienced devs, it is possible to use just about any API design pattern to build a usable API. But that doesn't mean different categories of APIs aren't better for specific scenarios than others.
If you need to build an API for your app, you'll want to determine which API design pattern best supports your needs. Or maybe which patterns, if building multiple APIs would fully address all your related use cases.
If you'd like to see how an embedded iPaaS makes it easier to build integrations with just about any type of API you are likely to come across, schedule a demo and we'll be glad to show you.
