What Is an API: The Restaurant Menu Analogy

Imagine walking into a restaurant. You don't walk into the kitchen and cook your own meal — you look at a MENU, which lists exactly what dishes are available and what each one contains. You tell the waiter what you want (your ORDER), the kitchen prepares it using whatever process they want (you never see or need to understand it), and the waiter brings you the finished dish (the RESPONSE). An API (Application Programming Interface) is exactly this same arrangement, but between two pieces of SOFTWARE instead of a customer and a kitchen.

The API is the menu: a defined list of things you're allowed to ask for (called endpoints or operations), what information you need to provide with each request, and what shape of answer you'll get back. Your code plays the customer — it sends a REQUEST specifying what it wants. The API provider's system plays the kitchen — it does whatever internal work is needed (querying a database, running a calculation, calling an AI model) and sends back a RESPONSE with the result. Crucially, just like you don't need to know how the kitchen cooks the dish, your code doesn't need to know HOW the API provider implements anything internally — you only need to know the menu (what requests are valid and what responses look like), a principle called abstraction.

This request/response cycle is the fundamental shape of almost every API you'll ever use: your code sends a request (specifying what you want, sometimes with extra details like search filters or data to submit), and gets back a response (the requested data, a confirmation, or an error message explaining what went wrong). This pattern is what lets software built by completely different teams, in completely different programming languages, running on completely different machines, work together seamlessly — your Python app can call OpenAI's API (built in whatever language they use, running on their servers) without either side needing to know anything about the other's internal implementation, as long as both sides agree on the 'menu.'

Why this matters enormously for AI applications: essentially every LLM you use through code — GPT-4, Claude, Gemini — is accessed through exactly this kind of API. You never run the actual model yourself; you send a request (your prompt) to the provider's API and get back a response (the generated text). Understanding the request/response menu-and-kitchen model is the foundation for everything else in this unit.

# The request/response pattern, illustrated with a plain Python
# function call standing in for 'making an API request' -- the
# CALLER never needs to know how process_order() works internally.

MENU = {
    "get_weather": "requires: city (str) -> returns: temperature, conditions",
    "get_recipe":  "requires: dish (str)  -> returns: ingredients, steps",
}

def api_request(endpoint: str, **params) -> dict:
    """Stand-in for calling a real API: send a request, get a response.
    The caller doesn't know or care HOW this is implemented."""
    if endpoint == "get_weather":
        # internal implementation is completely hidden from the caller
        return {"city": params["city"], "temperature_c": 22, "conditions": "Sunny"}
    if endpoint == "get_recipe":
        return {"dish": params["dish"], "ingredients": ["flour", "water", "salt"],
                "steps": ["Mix", "Knead", "Bake"]}
    return {"error": f"Unknown endpoint {endpoint!r} -- check the menu"}

print("Available API 'menu':")
for endpoint, description in MENU.items():
    print(f"  {endpoint}: {description}")

response = api_request("get_weather", city="Tokyo")
print(f"\nRequest: get_weather(city='Tokyo')")
print(f"Response: {response}")