APIs & the requests Library

• Explain what an API is — the "menu" a server offers to programs.
• Install and import the third-party requests library.
• Make a GET request, read the status code, parse the JSON body.
• Handle the obvious failure modes: no internet, 404, malformed JSON.

API stands for Application Programming Interface. Most of the time on the web, "API" means an HTTP endpoint that takes a URL and returns JSON.

GET https://icanhazdadjoke.com/
Accept: application/json
─────────────────────────────────────
200 OK
{"id": "...", "joke": "Why don't skeletons fight each other? They don't have the guts."}

The waiter analogy: you give the kitchen (server) an order via the menu (URL), it returns the dish (JSON). You don't need to know how the kitchen works.

Install once

requests is the de-facto HTTP library for Python. It's not built-in; install it once per environment:

pip install requests

The simplest call

import requests

r = requests.get("https://icanhazdadjoke.com/",
                 headers={"Accept": "application/json"})

print(r.status_code)   # 200 means success
print(r.json())        # the JSON body, parsed into a Python dict

200
{'id': 'R7UfaahVfFd', 'joke': "I'm reading a book about anti-gravity. It's impossible to put down.", 'status': 200}

What the response gives you

r.status_code   → int   (200, 404, 500, ...)
r.text          → str   (raw body, no parsing)
r.json()        → any   (body parsed as JSON)
r.headers       → dict  (response headers)
r.url           → str   (final URL after redirects)
r.ok            → bool  (True if status < 400)

Status codes — the three you'll see most

200  OK
404  Not Found        (wrong URL or missing resource)
500  Server Error     (their bug, not yours)

Handling failures

Two things can go wrong: the network itself, and a bad HTTP status. Handle both:

import requests

try:
    r = requests.get("https://icanhazdadjoke.com/",
                     headers={"Accept": "application/json"},
                     timeout=5)
    r.raise_for_status()         # raises if status >= 400
    data = r.json()
    print(data["joke"])
except requests.exceptions.RequestException as e:
    print(f"network error: {e}")
except ValueError:
    print("response was not valid JSON")

Always pass timeout=. Without it your program can hang indefinitely if the server gets stuck.

dog.ceo is a free no-key API that returns a random dog photo URL. Perfect for our first program.

# random_dog.py — first real API call
import requests
import webbrowser

URL = "https://dog.ceo/api/breeds/image/random"

try:
    r = requests.get(URL, timeout=5)
    r.raise_for_status()
except requests.exceptions.RequestException as e:
    print(f"❌ network error: {e}")
    raise SystemExit

data = r.json()
print("status:", data["status"])
print("photo: ", data["message"])

# Pop the dog up in your default browser
webbrowser.open(data["message"])

Sample output

status: success
photo:  https://images.dog.ceo/breeds/poodle-toy/n02113624_5060.jpg

The shape of the response is a dict with status and message keys. To know that, you check the API's docs — but you can also just print(data) the first time and read what came back.

Read the diff

Four lines do the actual work: get, raise_for_status, json, then use it. Everything else is error-handling boilerplate. From here every API is the same shape — only the URL and the response keys change.

An API is a URL the server promises will return data. requests.get(url) fetches it; .status_code, .json() and .raise_for_status() let you check and parse it. Always pass timeout=. Always handle RequestException. Tomorrow we level up with query parameters and headers.