Chapter 3: Your First API Call

When you're learning APIs, it helps to have a safe practice server that always behaves predictably. httpbin.org is exactly that: a free service built specifically for experimenting with HTTP. You can send it requests of all kinds, and it will simply show you, in plain JSON, what it received and how it interpreted your request.

In day-to-day work, developers use httpbin.org as a kind of Swiss Army knife for HTTP. It’s where you go when you want to:

• See exactly what headers your client is sending
• Inspect query parameters and request metadata
• Understand what cookies look like in requests and responses
• Test timeouts and slow responses with /delay
• Feel what different status codes look like in your code

Because it’s simple, predictable, and doesn’t require an account or API key, it’s perfect for experimenting and debugging without worrying about breaking anything.

In the rest of this chapter, you’ll use httpbin.org as your practice server while you build up real confidence with requests and responses.

Examples You'll Use

• httpbin.org/get - Returns the details of a GET request (headers, query parameters, URL)
• httpbin.org/status/404 - Returns a custom status code (like 404 Not Found)
• httpbin.org/json - Returns sample JSON data
• httpbin.org/delay/3 - Waits 3 seconds before responding (useful for testing timeouts)
• httpbin.org/image/png - Returns an image you can download or save to a file

Let's make your first request to httpbin. This will show you exactly what information your Python program sends when it makes a request.

The https://httpbin.org/get URL (often referred to as the /get endpoint on the httpbin.org server) simply echoes back everything it received:

• Headers: what your client sent automatically
• Origin IP: where the request came from
• Final URL: including any query parameters

It’s like holding up a mirror to your HTTP request so you can see it from the server’s point of view.

import requests

url = "https://httpbin.org/get"
response = requests.get(url, timeout=5)

print("Status:", response.status_code)
print("JSON:", response.json())

Status: 200
JSON: {
  "args": {},
  "headers": {
    "Accept": "*/*",
    "Host": "httpbin.org",
    "User-Agent": "python-requests/2.31.0"
  },
  "origin": "203.0.113.45",
  "url": "https://httpbin.org/get"
}

You might have noticed timeout=5 in the previous example. That small argument is not a nice-to-have; it's essential. Without a timeout, your program is willing to wait forever if a server never responds. “Forever” here is literal: that line of code will sit there blocked until you manually stop the script or restart the process.

By adding timeout=10, you’re telling requests: “Wait up to 10 seconds for this server to respond, then give up and raise an error.”

• Without a timeout: your program can hang indefinitely.
• With a timeout: your program fails fast and you can handle the exception.

Let’s start with a request that completes successfully with a timeout in place, then we’ll compare it to a request that deliberately takes too long.

import requests

response = requests.get("https://httpbin.org/get", timeout=10)
print("Request completed successfully!")
print(f"Status code: {response.status_code}")
print(f"Response type: {type(response)}")

Request completed successfully!
Status code: 200
Response type: <class 'requests.models.Response'>

The timeout=10 parameter tells requests to wait at most 10 seconds for the server to respond. If the server is slower than that, requests raises a Timeout exception instead of leaving your program stuck. That small safeguard makes a big difference to the reliability of your code.

Let’s deliberately trigger a timeout so you can see what it looks like in practice. httpbin.org has a /delay/N endpoint that waits N seconds before responding, which is perfect for testing timeout behavior. We’ll ask the server to wait 15 seconds, but we’ll only give it 5 seconds before we give up. This demonstrates exactly how timeout protection works:

import requests

# This server will delay for 15 seconds, but we'll only wait 5
response = requests.get("https://httpbin.org/delay/15", timeout=5)

Traceback (most recent call last):
  File "test.py", line 4, in <module>
    response = requests.get("https://httpbin.org/delay/15", timeout=5)
  ...
requests.exceptions.ReadTimeout: HTTPSConnectionPool(host='httpbin.org', port=443): 
Read timed out. (read timeout=5)

This timeout error is actually protecting your program. The message is telling you that the server did not respond within 5 seconds, so requests stopped waiting and raised an exception. That is exactly what you want in a real application: fail clearly and quickly rather than hang silently in the background.

Before you start pulling data out of a response, pause and make sure the request actually succeeded. The Response object from the requests library contains everything you need to check:

• Status: did the request succeed (200) or fail (404, 500)?
• Headers: what format did the server send back?
• Body: what data did you actually receive?

Professional developers don’t assume success. They inspect first, then write parsing code against what the server really returned.

Let’s examine a Response object systematically. We’ll make a request to httpbin’s /json endpoint, and then inspect the object to see what information is available. As you read through the output, notice how much metadata comes back in addition to the JSON itself:

import requests

response = requests.get("https://httpbin.org/json", timeout=10)

print(response)                  # Quick summary
print(f"Status Code: {response.status_code}")
print(f"Request Successful: {response.ok}")
print(f"Object Type: {type(response)}")

<Response [200]>
Status Code: 200 
Request Successful: True
Object Type: <class 'requests.models.Response'>

Status codes are three-digit numbers that tell you what happened with your request. They’re standardized across the web, so every API uses the same codes to mean the same things. Once you know the common ones, you can glance at a status code and immediately tell whether your request worked, failed, or needs a follow-up.

Beyond status codes, Response objects also carry headers: small pieces of metadata that provide extra context about the response. Headers tell you things like what format the data is in, when it was generated, and what server software sent it. You won’t read headers on every request, but when something feels “off,” they’re one of the first places to look.

Let’s write a more comprehensive inspection script that displays not just the status, but also key headers and other metadata. This is the kind of diagnostic code you might write when troubleshooting tricky API integration issues:

import requests

response = requests.get("https://httpbin.org/get", timeout=10)

# Examine the response object structure
print("Response Object Analysis")
print("=" * 50)
print(f"Object type: {type(response)}")
print(f"Status code: {response.status_code}")
print(f"Status text: {response.reason}")
print(f"Success check: {response.ok}")
print(f"Content length: {len(response.text)} characters")
print(f"Response URL: {response.url}")

# Show key headers
print("\nKey Response Headers:")
print(f"Content-Type: {response.headers.get('Content-Type')}")
print(f"Server: {response.headers.get('Server')}")
print(f"Date: {response.headers.get('Date')}")

Response Object Analysis
==================================================
Object type: <class 'requests.models.Response'>
Status code: 200
Status text: OK
Success check: True
Content length: 321 characters
Response URL: https://httpbin.org/get

Key Response Headers:
Content-Type: application/json
Server: gunicorn/19.9.0
Date: Sat, 06 Sep 2025 21:10:00 GMT

Not every API call will succeed. Common failures include:

• Servers go down or return errors
• Wi-Fi drops or networks fail mid-request
• URLs have typos or endpoints change
• Requests time out when services are slow

If you don’t handle these situations, your program will crash the moment something goes wrong. Professional developers expect failures and build in error handling so their applications can respond gracefully instead of blowing up.

First, let’s see what happens when things go wrong and there’s no protection in place. We’ll deliberately request a URL that returns a 404 error (Not Found), then call response.raise_for_status(). Notice how the program stops at the error and never reaches the code that comes afterwards:

import requests

response = requests.get("https://httpbin.org/status/404", timeout=5)
response.raise_for_status()  # This will crash the program
print("This line never executes")

Traceback (most recent call last):
  File "test.py", line 4, in <module>
    response.raise_for_status()
requests.exceptions.HTTPError: 404 Client Error: Not Found for url: https://httpbin.org/status/404

The program crashed with an HTTPError. The print() statement never executed because Python stopped as soon as raise_for_status() raised the exception. Now let’s add basic error handling so we can catch this exception and respond more gracefully:

import requests

try:
    response = requests.get("https://httpbin.org/status/404", timeout=5)
    response.raise_for_status()
    print("Success!")
except requests.exceptions.HTTPError as e:
    print(f"HTTP error occurred: {e}")
except requests.exceptions.Timeout:
    print("Request timed out")
except requests.exceptions.RequestException as e:
    print(f"An error occurred: {e}")

HTTP error occurred: 404 Client Error: Not Found for url: https://httpbin.org/status/404

Now, instead of crashing, the program catches the error, prints a clear message, and can continue running. This is the difference between a fragile script and code that’s on its way to being production-ready.

httpbin.org lets you simulate any HTTP status code using the /status/CODE endpoint. This is perfect for testing how your error handling behaves in different scenarios. Let’s create a small helper function that tries several status codes and prints how each one is handled. This kind of experimentation teaches you what to expect in real-world API usage:

import requests

def test_status_code(code):
    """Test how your code handles different status codes."""
    try:
        url = f"https://httpbin.org/status/{code}"
        response = requests.get(url, timeout=5)
        response.raise_for_status()
        print(f"✓ Status {code}: Success")
    except requests.exceptions.HTTPError as e:
        print(f"✗ Status {code}: {e}")

# Test different scenarios
test_status_code(200)  # Success
test_status_code(404)  # Not Found
test_status_code(500)  # Server Error
test_status_code(429)  # Rate Limited

✓ Status 200: Success
✗ Status 404: 404 Client Error: Not Found for url: https://httpbin.org/status/404
✗ Status 500: 500 Server Error: Internal Server Error for url: https://httpbin.org/status/500
✗ Status 429: 429 Client Error: Too Many Requests for url: https://httpbin.org/status/429

This kind of hands-on testing builds confidence. You see exactly how different status codes behave and what exceptions they raise. Later, when you encounter these codes in real APIs, you’ll already know what they mean and have a pattern for how to handle them.

Most real-world APIs need extra details in your request. When asking for weather data, you specify the location. When searching for videos, you provide search terms. When filtering results, you include your criteria. These extra pieces of information are sent as query parameters.

Query parameters are added to URLs after a ?, written as key=value pairs, and separated by &. They provide additional information that customizes the API’s response. Let’s break down the anatomy of a URL that uses query parameters:

https://httpbin.org/get?name=Alice&age=25&city=Boston
└──────────┬──────────┘ └──────────────┬──────────────┘
      Base URL                    Query Parameters

Breaking it down:
  ?name=Alice    ← First parameter (starts with ?)
  &age=25        ← Second parameter (starts with &)
  &city=Boston   ← Third parameter (starts with &)

To see how this works in practice, we’ll use httpbin.org’s /get endpoint. It echoes back whatever parameters you send, making it perfect for understanding how servers receive your data. Let’s send some parameters and look at exactly what the server reports back:

import requests

url = "https://httpbin.org/get?name=Alice&age=25&city=Boston"
response = requests.get(url, timeout=5)

print("Status:", response.status_code)
print("\nWhat the server received:")
data = response.json()
print("Parameters:", data["args"])

Status: 200

What the server received:
Parameters: {'name': 'Alice', 'age': '25', 'city': 'Boston'}

The server parsed the query string and extracted each parameter. Notice that age became a string ("25") even though you might think of it as a number. Query parameters are always transmitted as text; it’s up to the server to decide whether to interpret them as numbers, dates, or other types.

Manually building parameter strings is error-prone. What if a value contains spaces? Special characters? Symbols like & or =? The params argument in the requests library solves these problems by automatically handling URL encoding, type conversion, and formatting. It feels like a small convenience-until you run into the subtle bugs that manual string building can cause.

Let’s compare the manual approach (fragile) with the params approach (robust). This will show you why you should reach for params by default:

import requests

# Manual string building - fragile and error-prone
name = "Alice Smith"  # What if there's a space?
city = "New York"     # What about special characters?
url = f"https://httpbin.org/get?name={name}&city={city}"  # Easy to get wrong

response = requests.get(url, timeout=5)

import requests

# Clean, safe parameter passing
params = {
    "name": "Alice Smith",
    "city": "New York",
    "age": 25
}

response = requests.get("https://httpbin.org/get", params=params, timeout=5)

The params version automatically handles the spaces in "Alice Smith" and "New York" by encoding them safely in the URL. You don’t have to think about the low-level details; requests takes care of it.

Now let’s look at a complete example that shows how params handles multiple data types and what URL it actually constructs. Pay attention to the “Final URL” in the output-this is what params built for you automatically:

import requests

url = "https://httpbin.org/get"

# Use a dictionary for parameters
params = {
    "name": "Alice Smith",
    "age": 25,
    "city": "New York",
    "verified": True
}

response = requests.get(url, params=params, timeout=5)

print("Status:", response.status_code)
print("Final URL:", response.url)
print("\nWhat the server received:")
data = response.json()
for key, value in data["args"].items():
    print(f"  {key}: {value}")

Status: 200
Final URL: https://httpbin.org/get?name=Alice+Smith&age=25&city=New+York&verified=True

What the server received:
  name: Alice Smith
  age: 25
  city: New York
  verified: True

Now let’s put everything you’ve learned in this chapter to work in a small but complete program. You’ll:

• Fetch data from two public APIs
• Use timeouts and handle potential errors
• Parse JSON and extract the fields you care about
• Present the results in a user-friendly format

This is the complete API workflow end to end:

• Make a request
• Check for errors
• Parse JSON
• Display results

As you read the code, pay attention to how it’s organized into functions. This is the kind of structure you’ll use in real applications.

"""
Cat Facts and Jokes
A simple program that fetches random data from two different APIs.
"""

import requests

def get_cat_fact():
    """Fetch a random cat fact from catfact.ninja."""
    try:
        url = "https://catfact.ninja/fact"
        response = requests.get(url, timeout=5)
        response.raise_for_status()
        return response.json()["fact"]
    except requests.exceptions.RequestException as e:
        return f"Couldn't fetch cat fact: {e}"

def get_joke():
    """Fetch a random joke from official-joke-api."""
    try:
        url = "https://official-joke-api.appspot.com/random_joke"
        response = requests.get(url, timeout=5)
        response.raise_for_status()
        data = response.json()
        return f"{data['setup']} ... {data['punchline']}"
    except requests.exceptions.RequestException as e:
        return f"Couldn't fetch joke: {e}"

# Main program
print("=" * 50)
print("🐱 CAT FACTS & JOKES 🤣")
print("=" * 50)

print("\nHere's a cat fact for you:")
print(get_cat_fact())

print("\nAnd here's a joke:")
print(get_joke())

print("\n" + "=" * 50)

==================================================
🐱 CAT FACTS & JOKES 🤣
==================================================

Here's a cat fact for you:
Cats sleep for 70% of their lives, which means a 9-year-old cat 
has been awake for only three years of its life.

And here's a joke:
Why don't scientists trust atoms? ... Because they make up everything!

==================================================

Practice is where this really sticks. Try these small challenges to extend the program and test your understanding:

This mini-project isn’t just a toy example; it demonstrates patterns you’ll see in professional applications. Let’s highlight what makes it “production-style” code:

• Timeout on every request: No hanging calls, no infinite waits.
• Comprehensive error handling: Network issues and HTTP errors are caught and reported clearly.
• Function separation: Each API call lives in its own function, which makes it easier to test and reuse.
• Clear documentation: Docstrings explain what each function does at a glance.
• User-friendly output: The program prints clean, readable messages instead of raw JSON blobs.

These aren’t advanced tricks. They’re foundational habits you can apply to every API project. Starting with these patterns now means you won’t have to unlearn brittle, “demo-only” styles of code later.

In this chapter, you went from making your very first API call to building a small, multi-API program that feels like a real application. Along the way, you met the core ideas that show up in almost every API project: send a request, inspect the response, parse the data, and handle anything that goes wrong.

Key Concepts You Now Know

• How to make GET requests with requests.get() and talk to real web APIs.
• What a Response object is and how to read its status code, headers, and body.
• How JSON maps naturally onto Python dictionaries and lists, and how response.json() does the parsing for you.
• Why timeout=... is essential on every request so your program never hangs forever.
• How to use response.raise_for_status() and try/except blocks to handle errors gracefully.
• How query parameters work, and how the params argument builds safe URLs for you.
• How to structure code into small, focused functions that each handle a single API’s behavior.

None of these patterns are “toy” techniques. They’re the same building blocks used in production apps that talk to payment providers, weather services, mapping APIs, social media platforms, and more.

The Cat Facts and Jokes program might be playful, but the way you designed it, with timeouts, error handling, and clean JSON parsing, is exactly how serious systems are built.

As you move into the next chapters, you’ll reuse this same pattern over and over again: request → inspect → parse → handle errors → present results. The tools and APIs will change, but the mental model you built in this chapter will stay with you.

You've just crossed a major threshold. You wrote code that connects to real servers across the internet, receives live data, and parses that data into structures you can work with. You're no longer just running scripts that live entirely on your computer. You're building programs that talk to the outside world.

In this chapter, you:

• Sent real HTTP requests across the internet and received live responses
• Parsed JSON into Python dictionaries and lists
• Added timeouts so your code never hangs forever
• Handled common errors with try/except and raise_for_status()
• Customized requests with query parameters and the params argument
• Built a small project that combined multiple APIs into one script

If some of the concepts still feel a bit new, that's completely normal. The goal isn't to memorize every method or function; it's to feel comfortable with the overall flow of making requests, inspecting responses, and handling the cases where things go wrong. You've built that foundation, and everything from here builds on these patterns.

Test your understanding of the key concepts from this chapter:

You've learned how to make API calls, parse responses, and handle basic errors. But real-world APIs come with more complexity: authentication requirements, rate limits, pagination, and detailed error messages that you need to interpret correctly.

In the next chapter, you'll learn how to read API documentation like a professional developer. Documentation is where APIs explain their rules, endpoints, required parameters, and authentication schemes. Once you can read documentation fluently, you'll be able to integrate any API into your projects, not just the handful we've covered here.

You're building the skillset of a professional API developer, one chapter at a time. Keep going. You're doing great.