Different types of API

4 min readOct 27, 2020

I’m trying to learn more about APIs and quite frankly I’ve been feeling a bit overwhelmed about where on earth to start.

I’m someone who likes the big picture before narrowing in on something specific, so while I’ve been recommended to start learning more about REST (which is the most popular API architecture for the web right now) I wanted to get a basic understanding of what all the options were before digging into REST specifically. This is that big picture summary.

Categorizing different types of APIs

There’s different ways to categorize APIs, for example you can categorize them by who is going to be using them (e.g. open APIs where the intended consumer is lots of unknown users who all have open access, or private/partner APIs where the consumers are known and given access). This article breaks this way of categorization down much better than I will be here.

What I’m most interested in is the different types of API styles

API style options

Okay so here are the main styles of API:

RPC (XML/JSON)

An RPC is a ‘Remote Procedural Call’ protocol. They are the oldest and simplest types of APIs. The goal of an RPC was for the client to execute code on a server. XML-RPC used XML to encode its calls, while JSON-RPC used JSON for the encoding. Both are simple protocols (source).

SOAP (simple object access protocol)

Purely uses XML (cannot use JSON).
SOAP is very closely coupled with the server, having a strict communication contract with it that makes it more difficult to make changes or updates. A client interacting with a REST API needs no knowledge of the API, but a client interacting with a SOAP API needs knowledge about everything it will be using before it can even initiate an interaction. (source)
Strong security. SOAP uses WS-Security, which is stronger than things like SSL and HTTPS (which is used by REST).
SOAP is a protocol (rather than an architecture). I found this stack overflow useful for understanding the difference. TLDR;

Protocol

A protocol defines what type of conversation can take place between two components of a distributed application, by specifying messages, data types, encoding formats and so on.

Architecture

An architectural style is a coordinated set of architectural constraints that restricts the roles/features of architectural elements and the allowed relationships among those elements within any architecture that conforms to that style.

with the analogy:

A good analogy is to think of a protocol as how to write a message and REST as how a machine deals with a message it receives.

REST (Representational State Transfer)

REST came after SOAP and is not a protocol, it is a set of architectural principles. For an API to be RESTful, it must adhere to the following rules (source):

Stateless — A REST API is stateless in nature, Client-Server Architecture
Uniform Interface — A client and server should communicate with one another via HTTP (HyperText Transfer Protocol) using URIs (Unique Resource Identifiers), CRUD (Create, Read, Update, Delete) and JSON (JavaScript Object Notation) conventions.
Client-Server — The client and server should be independent of each other. The changes you make on the server shouldn’t affect the client and vice versa.
Cache — The client should have the ability to cache the responses as this improves the user experience by making them faster and more efficient.
Layered — The API should support a layered architecture, with each layer contributing to a clear hierarchy. Each layer should be loosely coupled and allow for encapsulation.

GraphQL

The most recent style, developed by facebook.
GraphQL is a query language for your API, and a server-side runtime for executing queries by using a type system you define for your data (from the docs).
Takes some inspiration from REST, and some from RPC so I’m breaking it into its own style (programmable web describe talk about it in this video).

Push/Streaming APIs

Push/Streaming APIs are event-driven. This means that when some event happens, data is then sent (or “pushed”) in near real-time to a client that’s waiting for such updates. In contrast, most REST-styles APIs use the same polling pattern where a client sends a request to a server, the server retrieves the requested data and then returns it back to the client. (source)
Push/Streaming APIs are enabled by a variety of underlying technologies such as Webhooks and WebSockets. But there are others available to providers in order to best enable their APIs for real-time streaming. For example, although it largely follows an RPC-like pattern, gRPC is built on top of HTTP/2 which in turn offers native support for bi-directional (server to client or client to server) streaming. (source)