An API is the interface that a software program presents to other programs, to humans, and, in the case of web APIs, to the world via the internet. An API’s design belies much about the program behind it — business model, product features, the occasional bug.
Although APIs are designed to work with other programs, they’re mostly intended to be understood and used by humans writing those other programs:
An object-oriented API can encapsulate a protocol, for example JMI in Java.
An API paradigm defines the interface exposing backend data of a service to other applications.
Types of API
We basically distinguish the following types of API's:
- Object-oriented API:
Language-independent.
For example: Java API.
- REST-API
This is the most used API.
Language - and platform-independent.
Data-centric.
- Messaging-API
Language - and platform-independent.
De-coupling.
For example: push notifications for mobile apps.
- File-based API
Asynchronous exchange of configuration files.
In addition, API's are also categorized with respect to your behavior. You participate in Event-Driven - and Request and Response APIs. Below is a brief overview of Event- Driven APIs.
Event-Driven APIs
To share data about events in real time, there are three common mechanisms:
WebHooks
WebSockets
HTTP Streaming
WebHooks
A WebHook is just a URL that accepts an HTTP POST (or GET, PUT, or DELETE). An API provider implementing WebHooks will simply POST a message to the configured URL when something happens.
The figure shows a typical activity diagram of a Web Hook.
WebSockets
WebSocket is a protocol used to establish a two-way streaming communication channel over a single Transport Control Protocol (TCP) connection. Although the protocol is generally used between a web client (for example a browser) and a server, it’s sometimes used for server-to-server communication as well.
A popular application example is a chat implementation.
This will also be possible in the future via HTT2.
The figure shows a typical activity diagram of a WebSocket.
HTTP Streaming
With the HTTP request– response APIs, clients send an HTTP request and the server returns an HTTP response of a finite length. Now, it’s possible to make the length of this response indefinite. With HTTP Streaming, the server can continue to push new data in a single long-lived connection opened by a client.
The figure shows a diagram illustrating the data flow of an client-server interaction with an HTTP streaming API.
Summary
Comparison: WebHooks, WebSockets, and HTTP Streaming
Comparison: WebHooks, WebSockets, and HTTP Streaming
| WebHooks | WebSockets | HTTP Streaming | |
|---|---|---|---|
| What? | Event notification via HTTP callback | Two-way streaming connection over TCP | Long-lived connection over TCP |
| Example services | Slack, Stripe, GitHub, Zapier, Google | Slack, Trello, Blockchain | Twitter, Facebook |
| Pros |
|
|
|
| Cons |
|
|
|
| When to use? | To trigger the server to serve real-time events | For two-way, real-time communication between browsers and servers | For one-way communication over simple HTTP |
The table above shows a compilation of the most important characteristics and behaviors of WebHooks, WebSockets, and HTTP Streaming.