Calling a Real API with requests

We finally connect to a live, real network API — the REST Countries API — using the requests library, replacing our local file with genuinely external, unpredictable data.

1. Learning Objective

2. Pre-Coding Quiz

Answer these before reading the concept explanation or writing any code. It is fine to get these wrong — that is the point. You need 4/5 to proceed to the lab.

3. The Concept — Calling a Real API

Making an HTTP request with requests

The requests library (installed via pip) provides a simple interface for making HTTP calls — a GET request fetches data from a URL.

# pip install requests
import requests

response = requests.get("https://www.apicountries.com/countries")
print(response.status_code)  # 200 means success

data = response.json()  # parses the JSON body into Python data structures
print(type(data))         # <class 'list'>
print(len(data))          # a few hundred countries

Checking the status code before trusting the response

Just like Session 11's validation-before-use discipline, always check that a request actually succeeded before trying to use its data.

response = requests.get("https://www.apicountries.com/countries")

if response.status_code == 200:
    data = response.json()
else:
    print(f"API request failed with status {response.status_code}")
    data = []

Adapting the API's shape to our own contract

A real, public API almost never returns exactly the shape you want. This particular API returns over 20 fields per country — area, flags, currencies, calling codes, borders — when our contract only needs three. An adapter function trims the response down to OUR agreed shape, so Country itself never needs to change or grow to accommodate data it does not use.

def adapt_api_record(raw):
    # The real API gives us 20+ fields; our contract only wants 3.
    # .get() with a default protects us if a field is ever missing.
    return {
        "name": raw.get("name", "Unknown"),
        "region": raw.get("region", "Unknown"),
        "population": raw.get("population", 0),
    }

api_records = [
    {
        "name": "Kenya", "region": "Africa", "population": 54000000,
        "area": 580367, "flag": "🇰🇪", "capital": ["Nairobi"],
        "currencies": {"KES": {"name": "Kenyan shilling"}},
    },
]
adapted = [adapt_api_record(r) for r in api_records]
print(adapted)  # [{'name': 'Kenya', 'region': 'Africa', 'population': 54000000}]
# Now this matches OUR contract exactly — area, flag, currencies are simply dropped,
# and Country.from_dict() works completely unchanged

Pointing the repository at the real API

Session 28's design proves itself for the third time: only how raw_data is obtained changes.

def fetch_countries_from_api():
    response = requests.get("https://www.apicountries.com/countries")
    if response.status_code != 200:
        return []
    return [adapt_api_record(r) for r in response.json()]

repo = CountryRepository(raw_data=fetch_countries_from_api())
print(len(repo.get_all()))  # real, live data — get_all() itself is completely unchanged

4. Lab

What you will build

A file called real_api_lab.py.

Step-by-step instructions

# real_api_lab.py
import requests

response = requests.get("https://www.apicountries.com/countries")
print("Status code:", response.status_code)

if response.status_code == 200:
    raw_data = response.json()
    print("Received", len(raw_data), "records")
else:
    raw_data = []
    print("Request failed")

if raw_data:
    print(sorted(raw_data[0].keys()))
    print(raw_data[0])

def adapt_api_record(raw):
    return {
        "name": raw.get("name", "Unknown"),
        "region": raw.get("region", "Unknown"),
        "population": raw.get("population", 0),
    }

adapted_records = [adapt_api_record(r) for r in raw_data]
print(adapted_records[0])  # now matches our own flat 3-field contract, extras dropped

from country_explorer import CountryRepository

repo = CountryRepository(raw_data=adapted_records)
print(len(repo.get_all()))
print(repo.get_all()[0].summary())

from country_explorer import validate_country_record

def fetch_and_build_repository():
    response = requests.get("https://www.apicountries.com/countries")
    if response.status_code != 200:
        print(f"API request failed with status {response.status_code}")
        return CountryRepository(raw_data=[])
    adapted = [adapt_api_record(r) for r in response.json()]
    return CountryRepository(raw_data=adapted)

repo = fetch_and_build_repository()
sample = repo._raw_data[0] if repo._raw_data else None
if sample:
    validate_country_record(sample)  # confirms the real, adapted data honors our contract
    print("Sample record honors the contract")

5. Expected Files Changed

6. Commit Checkpoint

Once the lab is complete and you can explain every line, make this exact commit:

git add real_api_lab.py docs/sessions/session-42/index.html
git commit -m "session-42: fetch real data from the REST Countries API and adapt it to our contract"

7. Code Review Checklist

Go through your code line by line and check each item:

8. Post-Coding Quiz

Same 5 questions. Take it again now that you have written and run the code. You need 4/5 to mark this session complete.

9. Reflection Questions

Think through these after the post-quiz. No right answer — they are for discussion.

10. What Breaks If This Knowledge Is Missing?

11. What We Learned