What is an API in Python?

In the last lesson you learned Named Tuples. That was a neat way to bundle a few related values together inside your own program. But here is the thing. Real apps rarely live alone. A weather app does not store the weather itself. A maps app does not own every road on Earth. They ask some other program for that data over the internet. The way one program asks another for data is called an API. That is what this lesson is about.

🤔 Why Do We Need APIs?

Say you are building a small app that shows today’s weather. You need the live temperature for a city. You do not own a weather station. You do not have a giant database of temperatures around the world. So where does the number come from?

Here is the pain. The data you need lives on someone else’s computer, far away. You cannot reach into their database and grab it yourself. They will not give you direct access either. That would be unsafe and messy.

An API solves this. It is a controlled doorway the other program opens up. Your code can ask for exactly the data it is allowed to see. And it gets a clean answer back.

🧩 So What Is an API, Really?

API stands for Application Programming Interface. That sounds heavy, so let us break it into plain words. It is simply a way for two programs to talk to each other. One program asks for something. The other program answers.

The key idea is that you do not need to know how the other program works inside. You just need to know how to ask. Think of it like a TV remote. You press the volume button and the volume goes up. You have no idea what happens inside the TV, and you do not need to. The remote is the interface. The buttons are the things you are allowed to press.

A web API is the same idea. But the other program lives on a server somewhere on the internet, and you talk to it over the network.

The waiter analogy

This is the picture that helps most people understand APIs.

Imagine you walk into a restaurant. You are hungry. The food is made in the kitchen. But you do not walk into the kitchen yourself, right? You sit down, and a waiter comes over.

• You tell the waiter what you want. That is your request.
• The waiter carries your order to the kitchen. You never see the kitchen.
• The kitchen makes the food and hands it back to the waiter.
• The waiter brings the food to your table. That is the response.

The waiter is the API. You (your app) are the customer. The kitchen is the server with all the data and logic. You never touch the kitchen directly, and you do not need to. You just talk to the waiter, and the waiter knows how to get things done.

📨 Request and Response

Every API conversation has two halves. Your program sends a request, and the server sends back a response. That is the whole loop.

A request is your app saying “please give me this thing” or “please do this for me”. For our weather app, the request means this. “Give me the current weather for London.”

A response is what comes back. It is the data you asked for, plus a little note saying whether things went okay. For the weather app, the response carries the temperature, the sky condition, the humidity, and so on.

Here is the back-and-forth, step by step:

The response also comes with a small number called a status code. It tells you, in short, how things went. You will meet these properly in the next lesson. But the famous one is 404, which means “not found”. A 200 means “all good, here is your data”.

🔗 The Endpoint: The Address You Ask

So your app wants to talk to the weather server. But a big server can do many different things. It can give weather. It can give a five-day forecast. It can search for a city. How does it know which one you want?

You pick the right endpoint. An endpoint is just a specific web address (a URL) that points to one specific thing the API can do.

Think of it like a big company with one phone number but many extensions. You dial the main number, then “press 1 for sales, press 2 for support”. Each extension reaches a different department. Each endpoint reaches a different feature of the API.

Here is what a weather endpoint might look like:

https://api.weather-example.com/current?city=London

Let us read that address from left to right:

• https://api.weather-example.com is the server you are talking to.
• /current is the specific feature you want, the current weather. That is the endpoint path.
• ?city=London is extra information you pass along, telling the server which city you mean. This part is called a query parameter.

Change /current to /forecast and you are now asking a different question to the same server. Same waiter, different order.

📦 JSON: The Format the Data Comes Back In

Okay, so the server sends a response. But in what shape? If the weather server replied in a messy paragraph of plain English, your code would have a hard time pulling out the temperature. Both sides need to agree on a tidy, predictable format. That format is almost always JSON.

JSON stands for JavaScript Object Notation. Do not let the name scare you. It is just a simple way to write down data using labels and values, so that any program can read it. If you have seen a Python dictionary, JSON will feel very familiar.

Here is what the weather response might look like in JSON:

{
  "city": "London",
  "temperature": 18,
  "condition": "Cloudy",
  "humidity": 72
}

Read it like a set of labels and their answers:

• "city" has the value "London".
• "temperature" has the value 18.
• "condition" has the value "Cloudy".
• "humidity" has the value 72.

The reason JSON is everywhere is that it works the same way no matter what language you use. The weather server might be written in one language and your app in Python. But both understand JSON perfectly. It is a shared language for data.

And the best part for us. In Python, JSON turns into a dictionary, which you already know how to use. So once the data arrives, reading the temperature is as easy as looking up a key:

# This is the weather data after Python reads the JSON response.
weather = {
    "city": "London",
    "temperature": 18,
    "condition": "Cloudy",
    "humidity": 72,
}

# Pull out just the pieces you care about.
print(f"It is {weather['temperature']}°C and {weather['condition']} in {weather['city']}.")

Running that prints a clean, friendly line:

It is 18°C and Cloudy in London.

That is the moment it all comes together. The weather started life on some distant server. It traveled to your app as JSON. It became a normal Python dictionary. And now you are using it like any other data in your program.

🌍 Putting It All Together

Let us walk the full path of our weather app one time, using every word you just learned.

So the full story reads like one smooth sentence. Your app sends a request to an endpoint of the weather API, and gets back a response in JSON, which your Python code reads like a dictionary. That is it. That is what an API is.

This same pattern is everywhere. When you open a maps app and it shows nearby restaurants, it called an API. When a finance app shows live stock prices, it called an API. When an app lets you “log in with Google”, it talked to Google’s API. Once you see this loop, you start spotting it in almost every app you use.

⚠️ Common Mistakes

A few ideas trip people up when they first meet APIs. Clear these now and the rest is smooth.

• Thinking an API is a single website you visit. It is not a page for humans to read. It is a doorway for programs, and the data it returns is meant for code, not for eyes.
• Mixing up the API and the server. The server is the kitchen that holds the data and does the work. The API is the waiter, the agreed way to ask. They are related but not the same thing.
• Expecting the response to be nicely worded English. It comes back as structured JSON, which looks like labels and values, not a friendly sentence.
• Forgetting that an API can say no. If you ask for a city that does not exist, or you are not allowed in, the response tells you so with a status code instead of the data.

In the example below, response is the JSON the server sent, already read into a Python dictionary. That is the same thing we called weather earlier.

# ❌ Avoid: assuming the data is always there and reaching straight in.
temperature = response["temperature"]  # Crashes if the server returned an error instead.

# ✅ Good: check that the key exists before you use it.
if "temperature" in response:
    print(response["temperature"])
else:
    print("The weather data did not come back. Try again.")

✅ Best Practices

Keep these habits in mind as you start working with APIs.

• Read the API’s documentation first. It tells you the endpoints, what to send, and what shape the response comes back in. It is the menu for the restaurant.
• Always expect that a request can fail. Networks drop, servers get busy, cities get typed wrong. Plan for the “no” answer, not just the happy one.
• Treat the JSON response as a dictionary in Python. Once you have it, looking up values is the same skill you already have.
• Never hard-code secret keys in code you share. Many APIs give you a private key to identify you, and it should be kept private.

🧩 What You’ve Learned

You now have the full mental model of how programs talk over the internet.

• ✅ An API is a controlled way for two programs to talk to each other.
• ✅ The waiter analogy: you (your app) order, the waiter (API) carries it to the kitchen (server), and brings back the food (data).
• ✅ A request is your app asking for something; a response is what comes back.
• ✅ An endpoint is the specific URL you ask for one specific thing.
• ✅ JSON is the tidy, label-and-value format the data comes back in, and Python reads it like a dictionary.

🚀 What’s Next?

You understand what an API is and how the request-response loop works. Now it is time to actually send one from Python and get real data back.

Making HTTP Requests