Chapter 1. Understanding Asynchronous APIs

To start, this chapter will cover the basics of Application Programming Interfaces (APIs) in general and specifically asynchronous APIs. We’ll touch on the difference between synchronous protocols like Hypertext Transfer Protocol (HTTP) and asynchronous protocols like MQ Telemetry Transport (MQTT), and we’ll introduce the idea of them representing either RESTful (HTTP) or EVENTful (MQTT) types of implementations.

We’ll then focus on EVENTful message design and cover the three main ways messages are designed: notifications, objects, and streams. We’ll also explore the way messages can represent actions that happened in the past (events) and actions that are meant to happen sometime in the future (commands).

With this as a foundation, we’ll have all that we need to move on to Chapter 2, where we explore the AsyncAPI format and how you can use that to document your EVENTful system design.

But first, let’s cover the basics of async APIs.

Reviewing the Basics of Asynchronous APIs

Asynchronous APIs have been around for a long time. In fact, one of the common protocols for implementing async APIs, MQTT, was first created in 1999. That is only a few years after the most common synchronous API protocol, HTTP, was first released (1991). As we’ll see shortly, the main difference between RESTful and EVENTful systems is the way data (e.g., messages) are passed between machines. We’ll see examples of both of these in the following sections.

Get What Are Asynchronous APIs? now with the O’Reilly learning platform.

O’Reilly members experience books, live events, courses curated by job role, and more from O’Reilly and nearly 200 top publishers.