Explaining APIs

After completing this lesson, you will be able to:

After completing this lesson, you will be able to:

  • Explain APIs

API: Introduction

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.

  • This is the most used API.

  • Language - and platform-independent.

  • Data-centric.

  • 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


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.


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.


Comparison: WebHooks, WebSockets, and HTTP Streaming

Comparison: WebHooks, WebSockets, and HTTP Streaming

 WebHooksWebSocketsHTTP Streaming
What?Event notification via HTTP callbackTwo-way streaming connection over TCPLong-lived connection over TCP
Example servicesSlack, Stripe, GitHub, Zapier, GoogleSlack, Trello, BlockchainTwitter, Facebook
  • Easy server-to-server communication
  • Uses HTTP protocol
  • Two-way streaming communication
  • Native browser support
  • Can bypass firewalls
  • Can stream over simple HTTP
  • Native browser support
  • Can bypass firewalls
  • Do not work across firewalls or in browsers
  • Handling failures, retries, security is hard
  • Need to maintain a persistent connection
  • Not HTTP
  • Bidirectional communication is difficult
  • Reconnections required to receive different events
When to use?To trigger the server to serve real-time eventsFor two-way, real-time communication between browsers and serversFor 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.

Log in to track your progress & complete quizzes