APIs explained with a restaurant analogy

An API is a contract for asking another system to do something or return data. In the restaurant analogy, the menu defines allowed requests, the waiter carries them, and the kitchen performs hidden implementation work.

At a glance

Question	Practical answer
When is it useful?	A weather client sends a city and receives structured temperature data without knowing how sensors, forecasts, and databases operate behind the API.
What should you do?	Use a browser or API client to call a public read-only endpoint; record the URL, method, status code, headers, and JSON body.
How do you know it worked?	A valid request returns the documented status and shape, while an invalid parameter produces a controlled client error rather than an unexplained crash.
Common failure	The restaurant analogy stops at the contract boundary; real APIs also need authentication, quotas, versioning, retries, and observability.

flowchart LR
  A[Question] --> B[APIs explained with a restaurant analogy]
  B --> C[Small example]
  C --> D[Evidence]

The important idea is not to stop at a definition: connect the concept to a small example and observable evidence.

Worked example

A weather client sends a city and receives structured temperature data without knowing how sensors, forecasts, and databases operate behind the API.

Before acting, write the success signal. Change one condition at a time, observe the result, and record assumptions. For APIs explained with a restaurant analogy, this separates what you know from what you are merely guessing.

Practice in 20–30 minutes

Goal: Use a browser or API client to call a public read-only endpoint; record the URL, method, status code, headers, and JSON body.

1. Record the starting state and your prediction.
2. Implement the smallest version without adding unnecessary tools.
3. Change exactly one input or constraint and repeat.
4. Save a command, screenshot, output, or checklist as evidence.

Expected result: A valid request returns the documented status and shape, while an invalid parameter produces a controlled client error rather than an unexplained crash.

What can go wrong

The restaurant analogy stops at the contract boundary; real APIs also need authentication, quotas, versioning, retries, and observability.

When the result differs from your prediction, do not change many things at once. Check inputs, versions, environment, permissions, and logs, then repeat from the smallest example.

Definition of done

• I can explain the concept in my own words.
• I completed the small example and kept evidence.
• I know one failure mode and how to check it.
• Someone else can repeat the work without guessing missing steps.

Go deeper

Use the linked resource or repository at the end of the page when you need a full implementation. Check current versions before applying commands to a real project.