What Is an API? The Restaurant Menu Version

API is one of those technical words that appears everywhere once you notice it.

Weather API.

Payment API.

Maps API.

OpenAI API.

Booking API.

Crypto API.

Shipping API.

Login API.

And if you are new to web technology, the word can sound like a locked door with three capital letters on it.

Very official.

Slightly unfriendly.

Possibly guarded by someone who says “endpoint” too often.

But the basic idea is not that scary.

An API is a way for one piece of software to talk to another piece of software.

That is the simple version.

Not the full technical version. Not the version with authentication flows, rate limits, SDKs, status codes, and developers saying “the docs are clear” while everyone else quietly disagrees.

Just the doorway:

An API is a structured way for systems to ask each other for things and get responses.

A website may ask a weather service for today’s forecast.

A mobile app may ask a server for your profile.

A shop may ask a payment service whether a transaction succeeded.

A chatbot interface may ask an AI model to generate a response.

Software talks to software constantly.

APIs are part of how that conversation stays organized instead of becoming a digital food fight.

The simple version

API stands for Application Programming Interface.

That phrase is accurate, but it is also the kind of phrase that makes normal people suddenly remember laundry.

So let’s translate it.

An API is a set of rules that lets one software system interact with another.

It defines things like:

• what can be requested;
• how to make the request;
• what information must be included;
• what format the response will use;
• what errors might happen;
• who is allowed to use it;
• how often it can be used.

A useful API is like a clear counter at a restaurant.

You do not walk into the kitchen and start opening drawers.

You look at the menu.

You place an order in the expected format.

The kitchen prepares what you asked for.

Then you receive a response.

Hopefully food.

In software, the “menu” is the API documentation.

The “order” is the request.

The “food” is the response.

The “kitchen shouting that you forgot something” is the error message.

This analogy is not perfect, because no analogy is allowed to survive contact with backend development. But it works surprisingly well.

Why APIs exist

Software systems need to share information and actions.

A website does not need to build everything from scratch.

A weather app does not personally own the sky.

A payment form does not need to become a bank.

A map widget does not need to store every road on Earth in a tiny emotional suitcase.

Instead, apps and websites connect to other systems.

APIs make that possible.

For example:

• a travel website can request flight data;
• a shop can send payment details to a payment processor;
• a blog can load comments from a comment service;
• a delivery app can ask for location data;
• a dashboard can request analytics from a server;
• a chatbot interface can send a prompt to an AI model;
• a real estate site can import listings from a CRM.

Without APIs, every software project would need to manually copy information, build everything itself, or ask humans to move data around like very tired pigeons.

APIs allow systems to cooperate.

Not emotionally.

Structurally.

Which is usually enough for software.

The restaurant menu analogy

Let’s stay with the restaurant analogy for a minute.

Imagine you are sitting at a table.

You want soup.

You do not enter the kitchen.

You do not inspect every pot.

You do not yell:

Give me whatever soup-shaped data you have.

You use the menu.

The menu tells you what is available.

Maybe:

• tomato soup;
• mushroom soup;
• chicken soup;
• soup of the day.

You choose one.

The waiter takes your order.

The kitchen sends back soup.

An API works similarly.

The API documentation tells developers what actions are available.

For example:

GET /weather/today
GET /users/123
POST /orders
DELETE /cart/item/45

These are not random spells.

They describe possible requests.

The software making the request does not need to know how the other system works internally.

It just needs to know what it can ask for and how to ask.

That is the beauty of an API.

It creates a boundary.

You do not need kitchen access.

You need a menu and a proper order.

Requests and responses

Most API conversations have two major parts:

• request;
• response.

A request is what one system sends.

A response is what the other system sends back.

For example, a weather app might send a request like:

Please give me the weather for London today.

The weather service might respond with:

{
  "city": "London",
  "temperature": 16,
  "condition": "Cloudy"
}

That is simplified, but it shows the shape.

The request asks for something.

The response returns data.

On the web, many APIs use HTTP, the same general protocol browsers use to load websites. I explained the broader browser-server chain in what happens when you open a website.

The difference is that a normal web page request usually returns HTML for humans to see.

An API request often returns structured data for software to use.

The human sees a weather app.

Behind the scenes, the app may see JSON.

Which is less cute but more useful to computers.

Endpoints: the specific doors

An endpoint is a specific address where an API can be accessed.

Think of the API as a building.

Endpoints are the doors.

One door might give you user data.

Another door might create an order.

Another door might return search results.

Another door might update account settings.

For example:

/api/users
/api/orders
/api/products
/api/weather

Each endpoint has a purpose.

A developer needs to know:

• which endpoint to call;
• what method to use;
• what data to send;
• what response to expect;
• what permissions are required.

This is why API documentation matters.

Bad API documentation is like a restaurant menu that says:

Food may exist. Ask correctly.

Not helpful.

Good documentation says:

Here is what you can request, here is how to request it, here is an example, here is what can go wrong, and here is what the response looks like.

Developers appreciate this.

Future developers appreciate it even more.

Future developers are often just current developers after one confusing afternoon.

API methods: GET, POST, PUT, DELETE

Many web APIs use HTTP methods.

These methods describe what kind of action the request wants.

The common ones are:

• GET
• POST
• PUT
• PATCH
• DELETE

They sound blunt because they are.

GET

GET asks for data.

Example:

GET /products

This might return a list of products.

A GET request should not usually change data. It is more like asking:

What do you have?

POST

POST sends new data or creates something.

Example:

POST /orders

This might create a new order.

It is more like saying:

Here is information. Please do something with it.

PUT

PUT usually replaces or updates a resource.

Example:

PUT /users/123

This might update user 123 with a new full version of the data.

PATCH

PATCH usually updates part of a resource.

Example:

PATCH /users/123

This might update only the email address or display name.

DELETE

DELETE removes something.

Example:

DELETE /cart/item/45

This might remove an item from a cart.

That one feels emotionally clear.

Of course, real APIs can be more complicated. But the basic idea is:

The method tells the API what kind of action you want.

Ask.

Create.

Update.

Remove.

Software etiquette, but with capital letters.

Data formats: why JSON is everywhere

APIs need a format for sending data.

One of the most common formats is JSON.

JSON stands for JavaScript Object Notation.

It looks like this:

{
  "name": "Jane",
  "topic": "APIs",
  "beginnerFriendly": true
}

JSON is popular because it is readable enough for humans and structured enough for software.

It uses key-value pairs.

For example:

"name": "Jane"

The key is name.

The value is Jane.

APIs may use other formats too, like XML, plain text, files, images, or binary data, depending on the situation.

But JSON is extremely common in modern web APIs.

If websites are the visible storefront, JSON is often the little box of organized information moving behind the counter.

Not glamorous.

Very useful.

API keys: the “who are you?” part

Many APIs are not open to everyone without limits.

They may require an API key.

An API key is a code used to identify the application or user making the request.

It is not exactly the same as a password, but it should still be protected.

An API key might be used to:

• track usage;
• enforce limits;
• connect requests to an account;
• prevent random public access;
• enable billing;
• control permissions.

For example, a weather API may allow 1,000 free requests per day for one API key.

If the key is leaked, someone else may use your quota.

Or worse, create costs.

This is why developers should not casually paste secret API keys into public code repositories.

The internet has bots that look for leaked keys.

Because apparently even secrets need predators now.

Some API keys are safe to use in frontend code because they are meant to be public or restricted by domain.

Others must stay on the server.

The API documentation should explain this.

If it does not, the documentation has chosen suspense.

Suspense is not ideal for security.

Authentication and authorization

Two words often appear near APIs:

• authentication;
• authorization.

They are related, but not identical.

Authentication

Authentication asks:

Who are you?

This might involve:

• API keys;
• login tokens;
• OAuth;
• username and password;
• signed requests;
• certificates.

Authentication proves identity.

Authorization

Authorization asks:

What are you allowed to do?

A user might be authenticated but not allowed to access certain data.

For example, you may be logged into a website, but that does not mean you can see the admin dashboard.

Very disappointing for chaos.

Very good for security.

APIs need both ideas.

Who is making the request?

What are they allowed to access?

Without those checks, an API can become a door that forgot it was supposed to be locked.

Status codes: the API’s mood numbers

APIs often use HTTP status codes to describe what happened.

These are three-digit numbers.

Some common ones:

• 200 OK
• 201 Created
• 400 Bad Request
• 401 Unauthorized
• 403 Forbidden
• 404 Not Found
• 429 Too Many Requests
• 500 Internal Server Error

Status codes are like the API’s mood numbers.

200 OK

Everything went fine.

The request worked.

Everyone remains calm.

201 Created

Something was created successfully.

Usually after a POST request.

400 Bad Request

The request was malformed or missing something.

The API is saying:

I cannot work with this.

401 Unauthorized

The request needs valid authentication.

The API is saying:

I do not know who you are.

403 Forbidden

The API knows who you are, but you are not allowed to do that.

The API is saying:

I know you, and still no.

404 Not Found

The requested resource does not exist.

Classic.

Famous.

Emotionally versatile.

429 Too Many Requests

You hit a rate limit.

The API is saying:

Please calm down.

500 Internal Server Error

Something broke on the server side.

The API is saying:

This one might be me.

Status codes are useful because software needs predictable ways to handle success and failure.

Humans get awkward silence.

APIs get numbers.

Rate limits: because APIs need boundaries

APIs often have rate limits.

A rate limit controls how many requests can be made in a certain time.

For example:

• 100 requests per minute;
• 1,000 requests per day;
• 10 requests per second;
• different limits for free and paid plans.

Rate limits exist because servers are not infinite.

APIs need to protect themselves from overload, abuse, accidents, and enthusiastic code loops.

A beginner may accidentally write code that asks an API the same question thousands of times.

Not malicious.

Just very committed.

Rate limits help prevent one user from consuming too many resources.

If you hit a rate limit, the API may return 429 Too Many Requests.

This is the API equivalent of:

I need space.

Fair.

REST APIs

You may hear the phrase REST API.

REST stands for Representational State Transfer.

That name is not beginner-friendly.

It sounds like furniture being moved through a philosophy department.

A REST API is a common style for designing web APIs.

REST APIs often use:

• URLs for resources;
• HTTP methods like GET and POST;
• status codes;
• structured responses, often JSON.

For example:

GET /articles
GET /articles/42
POST /articles
PATCH /articles/42
DELETE /articles/42

This style makes APIs predictable.

You can often guess the shape:

• collection of things;
• one specific thing;
• create a thing;
• update a thing;
• delete a thing.

Not every API is perfectly RESTful.

Developers will argue about this.

They enjoy it.

For beginners, the useful part is:

REST is a common way to organize API requests around resources and actions.

That is enough for the doorway.

APIs and websites

Websites use APIs constantly.

A page may load first, then use APIs to get more data.

For example:

• search results;
• comments;
• product inventory;
• user profile data;
• notifications;
• maps;
• payment status;
• recommendations;
• live chat;
• analytics;
• admin dashboards.

Sometimes a website is mostly a frontend interface talking to APIs.

The page you see may be the visible layer.

The data may come from backend APIs.

This is common in modern web apps.

A simple static blog may not need many APIs.

A complex app usually does.

This is why websites can feel fast and dynamic: parts of the page can update without reloading the whole thing.

The browser asks an API for new data.

The page updates.

The user says:

Nice.

The developer says:

Please do not look at the console.

APIs and AI tools

AI tools often use APIs too.

A chat interface may send your prompt to an AI model through an API.

The API receives the input, sends it to the model, gets a response, and returns it to the app.

That is simplified, but the shape is right.

If you want the broader AI foundation, I wrote a plain-English guide to what AI really is. The API part is the delivery mechanism: how the app communicates with the model or service.

This matters because “using AI” often means several systems are involved:

• the app interface;
• the backend server;
• the API request;
• the model;
• the response;
• the user interface showing the result.

The chatbot you see is not always the whole system.

It is the front desk.

The API is part of the message path behind it.

Which is why things like latency, rate limits, privacy, and cost can matter.

Even when the interface looks simple.

Simple interfaces often hide complicated kitchens.

Webhooks: APIs that call you back

A webhook is related to APIs, but it flips the direction.

With a normal API request, your system asks another system for something.

With a webhook, another system sends your system a message when something happens.

Example:

A payment service sends your website a webhook when a payment succeeds.

A form service sends a webhook when someone submits a form.

A shipping service sends a webhook when a package status changes.

The idea is:

Do not keep asking me if something happened. I will tell you when it happens.

Very efficient.

Very polite.

Also capable of causing confusion if misconfigured.

Webhooks usually require a URL where messages should be sent, and sometimes a secret or signature to verify that the message is real.

This matters because you do not want random strangers telling your website:

Hello, a payment succeeded.

when no payment succeeded.

Webhooks are useful.

They also need security.

Because software, like humans, should not believe every message it receives.

Common API mistakes beginners make

APIs are powerful, but beginners often run into similar problems.

Mistake 1: Confusing frontend and backend

Some API calls can happen safely from the browser.

Others should happen on the server.

If a secret API key is involved, it usually should not be exposed in frontend code.

A browser is not a safe hiding place.

It is more like a glass box with buttons.

Mistake 2: Ignoring error handling

APIs fail sometimes.

Networks fail.

Servers fail.

Rate limits happen.

Data can be missing.

A good app needs to handle errors gracefully.

Not just collapse into a vague message like:

Something went wrong.

Which is true, but not exactly a healing experience.

Mistake 3: Trusting the API response blindly

If your app receives data, it should still validate what matters.

APIs can return unexpected data.

Fields can be missing.

Types can change.

External services can behave differently than expected.

“Because the API said so” is not always enough.

Mistake 4: Not reading the documentation

I know.

Documentation can be dry.

Sometimes it reads like it was written by a printer that became sentient but not friendly.

But API docs explain the rules.

Skipping them is how people spend three hours discovering a required field was missing.

Mistake 5: Forgetting rate limits

If your app makes too many requests, the API may block or slow you down.

Design with limits in mind.

Cache when appropriate.

Do not ask the API the same question every half-second because your code got excited.

Mistake 6: Hardcoding everything

Hardcoding API URLs, keys, settings, or environment-specific values can create problems later.

Use configuration and environment variables where appropriate.

Future you deserves fewer traps.

Future you has enough tabs open.

What makes a good API?

A good API is not just “it works.”

A good API is understandable.

I like APIs that have:

• clear documentation;
• examples;
• predictable endpoints;
• useful error messages;
• stable behavior;
• reasonable authentication;
• versioning;
• rate limit information;
• clear data formats;
• security guidance;
• human-readable explanations.

A good API respects the developer’s time.

A bad API turns every request into a small archaeology project.

Good API design is a kindness.

Not a dramatic kindness.

No violins.

But the kind of kindness that means someone else does not have to guess what error_code_17 means at midnight.

Public APIs vs private APIs

Some APIs are public.

That means outside developers can use them, usually with an account, API key, documentation, and usage rules.

Examples might include APIs for:

• maps;
• weather;
• payments;
• AI tools;
• shipping;
• analytics;
• social platforms.

Other APIs are private.

They are used inside a company or application.

For example, a website’s frontend may talk to its own backend API, but that API is not meant for outside developers.

There are also partner APIs, internal APIs, open APIs, paid APIs, and APIs that technically exist but seem personally offended by being used.

The level of access matters.

Just because an API exists does not mean everyone should be able to use it.

Security is not optional.

It is the door.

A tiny glossary

API

An API is a structured way for one software system to communicate with another.

Endpoint

An endpoint is a specific API URL used for a particular action or resource.

Request

A request is the message sent to an API asking for data or an action.

Response

A response is what the API sends back after receiving a request.

JSON

JSON is a common data format used by APIs. It stores information in key-value pairs.

API key

An API key is a code used to identify or authorize API usage.

It should be protected if it grants access or usage rights.

Authentication

Authentication confirms who is making the request.

Authorization

Authorization controls what the requester is allowed to do.

Status code

A status code is a number that describes the result of an API request, such as success, missing data, or server error.

Rate limit

A rate limit controls how many requests can be made in a certain time period.

REST API

A REST API is a common style of API design that uses HTTP methods and resource-based URLs.

Webhook

A webhook is a way for one system to send another system a message automatically when something happens.

My take

An API is not as mysterious as it sounds.

It is a structured conversation between software systems.

One system asks.

Another responds.

The useful part is that the conversation has rules.

What can you ask for?

Where do you ask?

What format do you use?

Who is allowed?

What comes back?

What happens if something goes wrong?

That structure is what makes APIs powerful.

They let websites, apps, services, dashboards, payment systems, AI tools, maps, stores, and databases work together without every project needing to reinvent the universe from scratch.

The beginner mistake is thinking an API is a magical technical object.

It is more like a menu, a counter, and a set of rules.

Still technical.

Still capable of being confusing.

But not mystical.

A good API says:

Here is what I can do. Here is how to ask. Here is what I will send back.

And honestly, that is a pretty good model for communication in general.

Software figured out boundaries.

Some meetings could learn from this.

Related posts

Web May 23, 2026 12 min read

What Is Browser Cache? Why Websites Sometimes Remember Too Much

A beginner-friendly explanation of browser cache, why websites load faster, why old versions sometimes appear, and when clearing cache actually helps.

webbrowsercacheperformancecookiesbeginner

Read article →

Web April 15, 2026 17 min read

What Are Cookies? The Web's Tiny Memory Notes, Explained

A beginner-friendly explanation of browser cookies, sessions, logins, tracking, cookie banners, privacy, and why cookies are not automatically bad.

webcookiesprivacybrowsertrackingbeginner

Read article →

Web April 2, 2026 14 min read

What Does HTTPS Actually Mean? The Lock Icon Is Not a Trust Badge

A beginner-friendly explanation of HTTPS, encryption, certificates, browser warnings, and why the lock icon does not automatically mean a website is trustworthy.

webhttpssecuritybrowsersslbeginner

Read article →