What is an API? A plain explanation with real examples

What is an API, in one sentence?

API stands for application programming interface. In one sentence: it is the agreed way one program asks another program for something, knowing in advance what shape the reply will take.

Picture the order window at a restaurant. You do not walk into the kitchen or learn how the food is cooked. You order in a set way, "one burger, no onions", and a plate comes back that you recognize. The window is the API, the kitchen is the other service, and you are your app.

Illustration

This guide is for anyone who wants to understand how software actually works: a student, a shop owner, a founder building a first app. Instead of abstract examples, we use an app you already understand: a small store that sells, takes payments and sends notifications, or an appointment booking app.

Where are the APIs in your own app?

Open any modern online store and most of what happens is requests going back and forth between your app and other services. These are the common ones in a store or booking app:

Notice the last row: your app has an internal API of its own. The part running in the browser or on the phone asks the part running on the server for data. If that split is new to you, read frontend vs backend.

How does an API request work, step by step?

Take the payment moment in your store. A customer taps "Pay now" on a cart worth 250 riyals. Here is what happens in a few seconds:

1. 1
   The address

   Your app knows the payment service's address, like the address of an office you take a form to.

2. 2
   The request

   Your app sends exactly what the gateway asks for: amount, currency, order number and payment method.

3. 3
   The identity

   Your app attaches a secret key that proves the request comes from your store and not from someone using your name.

4. 4
   The reply

   The gateway answers in a known shape: status (approved or declined), a reference number, and the reason if it was declined.

5. 5
   The action

   Your app reads the reply and marks the order as paid and shows the thank-you page, or asks the customer to try again.

Request

What your app sends: what it wants, with which data

Response

What comes back: the result and data, or an error

Key

Proof that the request really comes from you

Documentation

The service's guide to what it accepts and returns

Every API in the world follows this same idea, however different the details. Understand one good example and you can read the rest.

What is the difference between an API and a webhook?

With an API, your app does the asking. But some things happen outside your app: the customer finishes paying on the bank's page, then closes the browser before coming back. How does your store learn the order is paid? That is the job of a webhook: the service itself calls your app and tells it what happened.

A well-built store uses both: it asks the gateway for the status when the customer returns, and it receives the payment notice by webhook as a safety net. That way a paid order is never lost because the customer's connection dropped.

Are APIs safe, and what are API keys?

Most paid or sensitive services ask for an API key: a long string that works like a password for your app. Whoever holds the key can make requests in your name, which makes it the most valuable part of any connection.

How do I connect payments, WhatsApp and sign-in without writing code?

The traditional route: read each service's documentation, write the code for requests and replies, handle errors and test every case. It teaches a lot, but each connection takes weeks. In Fanann you describe the app in Arabic or English and it is built with the connections in place, and you review the plan before anything is built in plan mode.

Local payment methods are ready to connect: mada, Apple Pay, STC Pay, Tabby, Tamara, KNET, Benefit and Fawry, along with phone sign-in with a one-time code, WhatsApp notifications and Google sign-in. The full list is on the integrations page and the payments page.

The last sentence of that prompt is the learning trick: ask for every service to be explained. After the build, open your project's code, read the part that sends the payment request, and ask Neo, the assistant, about any line you do not follow. The project is yours and you can export it.

Should I build my own API or use a ready-made one?

Everyone asks this once the idea clicks. The answer depends on what you need:

How can I learn APIs by building in a week?

If your goal is to understand software, here is a short plan that turns the concept into real experience with your own app:

1. 1
   Day 1An app with no connections

   Build a simple booking app in Fanann that lists and saves appointments. This is where you meet the internal API.

2. 2
   Day 2Sign-in

   Add phone sign-in with a one-time code, and watch what happens when you type a wrong code.

3. 3
   Day 3A WhatsApp notice

   Send the booking confirmation on WhatsApp, and find in the code the moment the request goes out.

4. 4
   Day 4Payment and webhook

   Add a deposit with mada or Apple Pay, and trace how a booking becomes Paid.

5. 5
   Day 5Testing

   Ask the QA Engineer to try the app and report bugs with screenshots, then fix them.

Do not memorize the definition of an API. Send a real request, read the reply, and you will understand it for good.

Frequently asked questions

Terms in this article