What Is an API? Explained With Everyday Kenyan Examples

Picture a busy restaurant in Westlands. You sit at a table and tell the waiter what you want. The waiter walks to the kitchen, passes your order to the chef, waits for the food, and brings it back to your table. You never enter the kitchen yourself.

An API works the same way:

• You (the client) are the customer. Your app needs data or wants something done.
• The waiter (the API) carries your request to the system that can fulfill it and brings the response back.
• The kitchen (the server) does the actual work: querying a database, processing a payment, or generating a report.

You do not need to know how the kitchen works. You just need to know what is on the menu (the API documentation) and how to place an order (the API request format).

When you buy airtime on the Safaricom app, here is what happens behind the scenes:

1. Your app sends a request to Safaricom's servers: "Deduct KES 100 from this number and load airtime."
2. Safaricom's system checks your balance, processes the deduction, and loads the airtime.
3. The server sends a response back: "Success. Transaction ID: QKL7890XYZ."

That entire exchange is an API call. Safaricom publishes the Daraja API so that developers can trigger M-Pesa payments, check balances, and reverse transactions from their own apps.

A developer building a food delivery app in Nairobi does not build a payment system from scratch. They call the M-Pesa API, pass the customer's phone number and the amount, and the API handles the rest.

// Simplified M-Pesa STK Push request
const response = await fetch('https://sandbox.safaricom.co.ke/mpesa/stkpush/v1/processrequest', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    BusinessShortCode: '174379',
    Amount: '100',
    PartyA: '254712345678',
    PhoneNumber: '254712345678',
    TransactionDesc: 'Lunch order',
  }),
});

const data = await response.json();
console.log(data);
// { MerchantRequestID: "29115-34620561-1", ResponseCode: "0", ... }

Think about tapping your SACCO card when you board a matatu. The card reader does not care who you are, what you had for breakfast, or where you are going after the ride. It only needs three things: a valid card number, the route, and the fare amount.

That is exactly how an API works. The server does not care about your app's internal code, which programming language you used, or your database schema. It only cares about the request format you agreed on.

This agreement is called an API contract. It specifies:

• The endpoint: the URL you send requests to (like the card reader location).
• The method: GET (read data), POST (create data), PUT (update data), DELETE (remove data).
• The request body: the data you send (like the card number and fare).
• The response: what comes back (like the receipt showing your new balance).

Not all APIs work the same way. Here are the types you will encounter as a beginner:

REST APIs are the most common. They use HTTP methods (GET, POST, PUT, DELETE) and return JSON data. The M-Pesa Daraja API is a REST API. Most web services you will work with use REST.

// REST API example: fetch a list of users
const res = await fetch('https://api.example.com/users');
const users = await res.json();
// [{ id: 1, name: "Wanjiku" }, { id: 2, name: "Ochieng" }]

GraphQL APIs let you specify exactly which fields you want. Instead of getting a full user object with 20 fields, you can ask for just the name and email. GitHub's API v4 uses GraphQL.

// GraphQL query: only get what you need
const query = `{
  user(id: 1) {
    name
    email
  }
}`;

WebSocket APIs keep a connection open for real-time data. Chat apps and live score trackers use WebSockets because waiting for the client to ask "any new messages?" every second is wasteful.

Webhook APIs are the reverse of normal APIs. Instead of you asking the server for data, the server calls your URL when something happens. M-Pesa sends a callback to your server when a payment completes. We cover webhooks in detail in a separate article.

Open your terminal and run this command. No setup needed, no account required:

curl https://api.github.com/users/octocat

You just made a GET request to GitHub's public API. The response is a JSON object with data about the user "octocat":

{
  "login": "octocat",
  "id": 583231,
  "name": "The Octocat",
  "company": "@github",
  "public_repos": 8,
  "followers": 12000
}

You can do the same thing in JavaScript. Create a file called api-test.js and run it with Node:

// api-test.js
async function main() {
  const response = await fetch('https://api.github.com/users/octocat');
  const user = await response.json();
  console.log(`Name: ${user.name}`);
  console.log(`Public repos: ${user.public_repos}`);
}

main();

node api-test.js
# Name: The Octocat
# Public repos: 8

That is a real API call. The same principle applies whether you are fetching GitHub profiles, triggering M-Pesa payments, or pulling weather data. The URL changes, the authentication changes, but the pattern stays the same: send a request, get a response.

Every API comes with documentation that tells you what endpoints exist, what data to send, and what response to expect. Here is what a typical API doc entry looks like:

POST /api/v1/orders

Headers:
  Authorization: Bearer <token>
  Content-Type: application/json

Body:
  {
    "item": "Nyama Choma Platter",
    "quantity": 2,
    "delivery_address": "Kilimani, Nairobi"
  }

Response (201 Created):
  {
    "order_id": "ORD-4521",
    "status": "confirmed",
    "estimated_delivery": "45 minutes"
  }

The documentation tells you:

• The HTTP method (POST) and path (/api/v1/orders).
• What headers to include (authentication token, content type).
• What data to send in the body.
• What the response looks like when things go right.
• What error responses look like when things go wrong.

Good API documentation also includes example requests in multiple languages, error code tables, and rate limit details. Safaricom's Daraja docs, Paystack's docs, and Stripe's docs are all excellent references to study.