Table of Contents

1. Introduction
   • The Problem (Language & Translator Analogy)
2. Definition of an API
3. Core Concepts of API Communication
   • Message Format
   • Medium (Transport Layer)
4. Why Interfaces Matter in Software Development
   • Abstraction & Simplicity
   • The Problem Without an Interface
5. API Types — Deep Dive with Examples
   • 5.1 Library / SDK APIs
     • Medium & Format
     • Examples
   • 5.2 OS APIs
     • Medium & Format
     • Examples
   • 5.3 Web APIs
     • Medium & Format
     • API Styles:
       • REST
       • GraphQL
       • gRPC
       • WebSocket
     • Code Examples
   • 5.4 Database APIs
     • Medium & Format
     • Drivers vs ORMs
     • Examples
6. The Full Picture
   • Comparative Table of API Types
   • Key Insight: Medium vs Format
7. Conclusion
   • APIs as Translators Between Systems
8. References

---

Understanding APIs

The Problem

Let's say you travel to a foreign country, and you can't speak the local language — but you need to do business, buy things, eat, and get around.[1]

You have two options:

Option 1 — Learn the language. This takes time. How long depends on the learning curve of that language. Until you're fluent, you're stuck.

Option 2 — Hire a translator. The translator speaks your language and the country's language. You tell the translator your intent, and they transmit it to whoever you need to communicate with — and bring the response back to you.

That is exactly the problem an API solves.

---

Definition

An API (Application Programming Interface) is an interface that facilitates communication between two pieces of software , for instance software A and B .[2]

Communication is the act of sending messages / data across a medium.

This means an API has to deal with two things:

• Message Format — how the data is structured (e.g. JSON, XML)
• Medium — how the data travels (e.g. HTTP, memory, sockets)

Why Do We Need an Interface In Software Developement ?

The short answer: because you don't need to understand how something works in order to use it. [3] If software A want to use B , software doesnot need to know how B internally works . the concept of interface are also used in hardware development. The next section illustrate which problem the concept interface solve.

---

The Problem Without an Interface

Imagine if every time you wanted to use a feature of your operating system, you had to write the code that controls the hardware directly. Want to save a file? You'd need to know:

• Which physical sectors of the hard drive to write to
• How the file system is structured at the binary level
• How to talk to the disk controller chip

That's obviously impossible for most developers. An interface hides all that complexity and gives you a simple handle: fs.writeFile('notes.txt', content).

---

I think the above section , makes it clear , how useful Application Programming Interface is in developement . Now let us speak about the differents of API’s with example .

API Types — Deep Dive with Examples

Every API communication involves two inseparable components: what is being sent, and how it travels. In this section , we are going to discuss about the different types of API with their various format and medium of transport .

1. Library / SDK APIs

You call functions from a package or language built-in directly inside your code. No network involved.[4]

• Medium: Memory — the call happens inside the same running process
• Format: Native language types — objects, arrays, strings, numbers (no serialization needed)

Since everything happens in-process, there is no network hop, no HTTP, no JSON. You pass a JavaScript object and get a JavaScript object back — the language itself is the format.

Examples:

• Array.sort() — JavaScript standard library
• pandas.read_csv() — Python data library
• stripe.charges.create() — Stripe SDK

---

2. OS APIs

Your application asks the operating system for access to hardware or system resources — file system, camera, network, memory.[5]

• Medium: System calls — a controlled bridge between your app and the OS kernel
• Format: Binary / native OS structures — the OS speaks in low-level data structures, not JSON

You never talk to the hardware directly. The OS exposes an interface — a set of system calls — and manages the hardware on your behalf.

Examples:

• Reading a file: fs.readFile('notes.txt') → OS reads from disk and returns bytes
• Accessing the camera: navigator.mediaDevices.getUserMedia() → OS hands you a media stream
• Sending a desktop notification

// Your app asks the OS (via the browser's OS API bridge) for camera access
// Medium: system call. Format: binary media stream
const stream = await navigator.mediaDevices.getUserMedia({ video: true });

---

3. Web APIs

Two separate systems — often on different machines — communicate over a network. This is the most common type of API you'll work with as a developer. [6]

• Medium: Internet over HTTP / HTTPS (or WebSocket for real-time)
• Format: JSON (most common today), XML (older/enterprise), Binary like Protobuf (high-performance)

Web APIs come in several styles — each making different trade-offs:

// REST — Medium: HTTPS, Format: JSON
// You send an HTTP request, you get JSON back
fetch('https://api.github.com/users/octocat')
  .then(res => res.json())   // parse the JSON format
  .then(user => console.log(user.name));`

// WebSocket — Medium: persistent TCP connection, Format: JSON
// No request/response cycle — the server can push data at any time
const socket = new WebSocket('wss://chat.myapp.com');
socket.onmessage = (event) => {
  const message = JSON.parse(event.data); // parse incoming JSON
  console.log(message.text);
};

---

4. Database APIs

Your backend communicates with a database to read and write data. The database lives either on the same machine or a remote server.[7]

• Medium: TCP socket — a direct network connection to the database process
• Format: SQL statements (text protocol) or binary wire protocols (e.g. PostgreSQL wire protocol)

You rarely speak to the database directly — you use a driver or an ORM that wraps the raw protocol into something readable.

Examples:

• Data seeding and Migration, read this article to understand those terms
  • https://www.alainngongang.dev/posts/from-external-api-to-database-a-structured-data-pipeline-pattern-for-modern-web-apps
• Raw driver: pg sends SQL text over TCP, gets back binary rows
• ORM: Drizzle/Prisma translates your code into SQL, then hands it to the driver

// ORM layer — you write code, Drizzle translates to SQL, driver sends over TCP
// Medium: TCP socket. Format: SQL → PostgreSQL wire protocol
const users = await db.select().from(usersTable).where(eq(usersTable.id, 1));

---

The Full Picture

Every API type answers the same two questions differently:

The medium is the road. The format is the language.

The API is the translator that makes it all work.

REFERENCES

[1] Merriam-Webster. "Communication." Merriam-Webster Dictionary, 2024. https://www.merriam-webster.com/dictionary/communication

[2] MDN Web Docs. "Introduction to Web APIs." Mozilla Developer Network, 2024. https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Client-side_web_APIs/Introduction

[3] Gamma, E., Helm, R., Johnson, R., Vlissides, J. "Design Patterns: Elements of Reusable Object-Oriented Software." Addison-Wesley, 1994. https://en.wikipedia.org/wiki/Design_Patterns

[4] npm Documentation. "About packages and modules." npm, Inc., 2024. https://docs.npmjs.com/about-packages-and-modules

[5] Linux Foundation. "The Linux Kernel API." kernel.org, 2024. https://www.kernel.org/doc/html/latest/core-api/index.html

[6] Fielding, R. "Architectural Styles and the Design of Network-based Software Architectures." University of California, Irvine — Doctoral Dissertation, 2000. https://ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm

[7] PostgreSQL Global Development Group. "PostgreSQL Frontend/Backend Protocol." postgresql.org, 2024. https://www.postgresql.org/docs/current/protocol.html

Thanks for reading

Alain Ngongang