feat: add Module 03 — REST APIs: Consuming

Five progressive projects teaching REST API consumption with Python
requests library against JSONPlaceholder. Covers GET/POST requests,
query parameters, error handling with retries, and building a reusable
API client class with requests.Session.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: travisjneuman

projects/modules/03-rest-apis/01-first-api-call/README.md

@@ -0,0 +1,80 @@
+# Module 03 / Project 01 — First API Call
+
+[README](../../../../README.md)
+
+## Focus
+
+- Making a GET request with `requests.get()`
+- Understanding response objects (status code, headers, body)
+- Parsing JSON responses into Python dictionaries
+
+## Why this project exists
+
+Before you can build anything that talks to the internet, you need to understand the basic request-response cycle. This project strips it down to the simplest possible case: fetch one resource, look at what comes back, and pull out the pieces you care about.
+
+## Run
+
+```bash
+cd projects/modules/03-rest-apis/01-first-api-call
+python project.py
+```
+
+## Expected output
+
+```text
+--- Raw JSON response ---
+{
+  "userId": 1,
+  "id": 1,
+  "title": "sunt aut facere repellat provident occaecati excepturi optio reprehenderit",
+  "body": "quia et suscipit\nsuscipit recusandae consequuntur expedita et cum\nreprehenderit molestiae ut ut quas totam\nnostrum rerum est autem sunt rem eveniet architecto"
+}
+
+--- Accessing individual fields ---
+Status code : 200
+Post ID     : 1
+User ID     : 1
+Title       : sunt aut facere repellat provident occaecati excepturi optio reprehenderit
+Body preview: quia et suscipit...
+
+--- Response headers (selected) ---
+Content-Type: application/json; charset=utf-8
+```
+
+## Alter it
+
+1. Change the URL to fetch post `/posts/5` instead of `/posts/1`. Run again and compare the output.
+2. Print the full `body` field instead of just the first 20 characters.
+3. Add a line that prints the number of characters in the title.
+
+## Break it
+
+1. Change the URL to `https://jsonplaceholder.typicode.com/posts/99999` (a post that does not exist). What status code do you get? What does `response.json()` return?
+2. Remove the `.json()` call and print `response.text` instead. What is the difference?
+3. Change the URL to an invalid domain like `https://not-a-real-domain-xyz.com/posts/1`. What error do you get?
+
+## Fix it
+
+1. Add a check: if `response.status_code` is not 200, print a warning and skip the JSON parsing.
+2. Wrap the `requests.get()` call in a `try/except` block that catches `requests.exceptions.ConnectionError` and prints a friendly message instead of a traceback.
+3. After fixing, run with both a valid and invalid URL to confirm both paths work.
+
+## Explain it
+
+1. What does `response.json()` actually do under the hood?
+2. What is the difference between `response.text` and `response.json()`?
+3. Why does `requests.get()` return a Response object instead of just the data?
+4. What HTTP method does `requests.get()` use, and what does that method mean?
+
+## Mastery check
+
+You can move on when you can:
+
+- write a GET request from memory without looking at docs,
+- explain what a status code of 200 means vs 404,
+- extract any field from a JSON response,
+- describe the difference between `.text` and `.json()`.
+
+## Next
+
+Continue to [Query Parameters](../02-query-parameters/).

projects/modules/03-rest-apis/01-first-api-call/notes.md

@@ -0,0 +1,10 @@
+# Notes — First API Call
+
+## What I learned
+
+
+## What confused me
+
+
+## What I want to explore next
+

projects/modules/03-rest-apis/01-first-api-call/project.py

@@ -0,0 +1,64 @@
+"""Module 03 / Project 01 — First API Call.
+
+Learn how to fetch data from a REST API using requests.get(),
+inspect the response object, and parse JSON into a Python dictionary.
+"""
+
+# requests is the most popular HTTP library for Python.
+# You installed it with: pip install requests
+import requests
+
+# json is part of the standard library. We use it here only for
+# pretty-printing (indent=2), not for parsing — requests handles that.
+import json
+
+
+def fetch_single_post():
+    """Fetch one post from JSONPlaceholder and explore the response."""
+
+    # The URL points to a single post resource.
+    # JSONPlaceholder provides 100 fake posts at /posts/1 through /posts/100.
+    url = "https://jsonplaceholder.typicode.com/posts/1"
+
+    # requests.get() sends an HTTP GET request and returns a Response object.
+    # The Response object contains everything the server sent back:
+    # status code, headers, body, encoding, and more.
+    response = requests.get(url)
+
+    # --- Raw JSON response ---
+    # response.json() parses the response body from a JSON string into
+    # a Python dictionary (or list, depending on what the API returns).
+    # This only works if the server actually sent JSON — otherwise it raises
+    # a JSONDecodeError.
+    data = response.json()
+
+    print("--- Raw JSON response ---")
+    # json.dumps() converts the dictionary BACK into a formatted string.
+    # indent=2 makes it human-readable. This is just for display.
+    print(json.dumps(data, indent=2))
+
+    # --- Accessing individual fields ---
+    # Once parsed, `data` is a plain Python dict. You access fields with
+    # square brackets, just like any dictionary.
+    print("\n--- Accessing individual fields ---")
+    print("Status code :", response.status_code)
+    print("Post ID     :", data["id"])
+    print("User ID     :", data["userId"])
+    print("Title       :", data["title"])
+
+    # Slice the body to show just the first 20 characters as a preview.
+    print("Body preview:", data["body"][:20] + "...")
+
+    # --- Response headers ---
+    # The server sends metadata in HTTP headers. response.headers is a
+    # case-insensitive dictionary. Content-Type tells you the format of
+    # the response body.
+    print("\n--- Response headers (selected) ---")
+    print("Content-Type:", response.headers.get("Content-Type"))
+
+
+# This guard ensures the code below only runs when you execute this file
+# directly (python project.py). If another file imports this module,
+# the code below will NOT run. This is a Python best practice.
+if __name__ == "__main__":
+    fetch_single_post()

projects/modules/03-rest-apis/02-query-parameters/README.md

@@ -0,0 +1,80 @@
+# Module 03 / Project 02 — Query Parameters
+
+[README](../../../../README.md)
+
+## Focus
+
+- Passing query parameters with the `params` dict
+- Filtering API results by field values
+- Paginating results with `_limit` and `_start`
+- Understanding the difference between params dict and URL string
+
+## Why this project exists
+
+Most APIs return too much data if you do not tell them what you want. Query parameters are how you filter, sort, and paginate results. This project teaches you two ways to attach parameters to a request and shows you how to work with lists of results instead of a single resource.
+
+## Run
+
+```bash
+cd projects/modules/03-rest-apis/02-query-parameters
+python project.py
+```
+
+## Expected output
+
+```text
+--- Method 1: params dict ---
+Fetching posts by user 3 (using params dict)...
+Found 10 posts by user 3.
+  Post 21: ea molestias quasi exercitationem repellat qui ipsa sit aut
+  Post 22: delectus ullam et corporis nulla voluptas sequi
+  Post 23: nesciunt iure omnis dolorem tempora et accusantium
+  (showing first 3)
+
+--- Method 2: URL string ---
+Fetching posts by user 3 (using URL string)...
+Found 10 posts by user 3.
+
+--- Pagination ---
+Page 1: fetched 5 posts (IDs: 1, 2, 3, 4, 5)
+Page 2: fetched 5 posts (IDs: 6, 7, 8, 9, 10)
+Page 3: fetched 5 posts (IDs: 11, 12, 13, 14, 15)
+```
+
+## Alter it
+
+1. Change the `userId` filter to a different user (1 through 10 are valid). How many posts does each user have?
+2. Change the page size from 5 to 3 and fetch 5 pages instead of 3.
+3. Combine filtering and pagination: fetch user 1's posts, 2 at a time.
+
+## Break it
+
+1. Pass `userId=999` — a user that does not exist. What does the API return? Is it an error or an empty list?
+2. Set `_limit=0`. What happens?
+3. Pass `params={"userId": [1, 2]}` — a list instead of a single value. Does the API handle it? What do you get back?
+
+## Fix it
+
+1. Add a check after each request: if the response is an empty list, print "No results found" instead of trying to iterate.
+2. Add validation before the request: if `user_id` is not between 1 and 10, print a warning.
+3. After fixing, test with both valid and invalid user IDs.
+
+## Explain it
+
+1. What is the difference between passing `params={"userId": 3}` and putting `?userId=3` directly in the URL string?
+2. Why does JSONPlaceholder return an empty list instead of a 404 when you filter by a nonexistent user?
+3. How does `_start` differ from `_page` in pagination schemes you might encounter in other APIs?
+4. When would you choose params dict over URL string in your own code?
+
+## Mastery check
+
+You can move on when you can:
+
+- pass query parameters using both methods,
+- paginate through results using `_start` and `_limit`,
+- handle empty results gracefully,
+- explain why the params dict is usually preferred.
+
+## Next
+
+Continue to [POST and Auth](../03-post-and-auth/).

projects/modules/03-rest-apis/02-query-parameters/notes.md

@@ -0,0 +1,10 @@
+# Notes — Query Parameters
+
+## What I learned
+
+
+## What confused me
+
+
+## What I want to explore next
+

projects/modules/03-rest-apis/02-query-parameters/project.py

@@ -0,0 +1,98 @@
+"""Module 03 / Project 02 — Query Parameters.
+
+Learn how to pass query parameters to filter and paginate API results.
+Covers two approaches: the params dict and the URL string.
+"""
+
+import requests
+
+
+def fetch_posts_by_user_params_dict(user_id):
+    """Fetch all posts by a specific user using the params dict approach.
+
+    The params dict is the preferred way to pass query parameters.
+    requests will URL-encode the values and append them to the URL
+    automatically: /posts?userId=3
+    """
+    url = "https://jsonplaceholder.typicode.com/posts"
+
+    # Pass parameters as a dictionary. requests turns this into
+    # ?userId=3 appended to the URL. This approach is cleaner and
+    # handles special characters (spaces, &, =) automatically.
+    params = {"userId": user_id}
+    response = requests.get(url, params=params)
+    posts = response.json()
+
+    print("--- Method 1: params dict ---")
+    print("Fetching posts by user {} (using params dict)...".format(user_id))
+    print("Found {} posts by user {}.".format(len(posts), user_id))
+
+    # Show a preview of the first 3 posts.
+    for post in posts[:3]:
+        print("  Post {}: {}".format(post["id"], post["title"]))
+    if len(posts) > 3:
+        print("  (showing first 3)")
+
+    return posts
+
+
+def fetch_posts_by_user_url_string(user_id):
+    """Fetch all posts by a specific user using a URL string.
+
+    This approach puts the query parameters directly in the URL.
+    It works but is harder to maintain — you have to handle URL encoding
+    yourself and the URL becomes harder to read with many parameters.
+    """
+    # Here we build the URL string ourselves. For simple cases this is
+    # fine, but with multiple parameters or special characters, the
+    # params dict approach is safer.
+    url = "https://jsonplaceholder.typicode.com/posts?userId={}".format(user_id)
+
+    response = requests.get(url)
+    posts = response.json()
+
+    print("\n--- Method 2: URL string ---")
+    print("Fetching posts by user {} (using URL string)...".format(user_id))
+    print("Found {} posts by user {}.".format(len(posts), user_id))
+
+    return posts
+
+
+def paginate_posts(page_size, num_pages):
+    """Fetch posts in pages using _start and _limit parameters.
+
+    JSONPlaceholder supports pagination with:
+    - _start: the index to start from (0-based)
+    - _limit: how many items to return
+
+    Other APIs might use page/per_page or offset/limit instead.
+    The concept is the same: fetch a slice of the full dataset.
+    """
+    url = "https://jsonplaceholder.typicode.com/posts"
+
+    print("\n--- Pagination ---")
+
+    for page_num in range(1, num_pages + 1):
+        # _start is 0-based. Page 1 starts at 0, page 2 starts at page_size, etc.
+        start = (page_num - 1) * page_size
+
+        params = {
+            "_start": start,
+            "_limit": page_size,
+        }
+
+        response = requests.get(url, params=params)
+        posts = response.json()
+
+        # Build a comma-separated string of post IDs for display.
+        ids = ", ".join(str(post["id"]) for post in posts)
+        print("Page {}: fetched {} posts (IDs: {})".format(page_num, len(posts), ids))
+
+
+if __name__ == "__main__":
+    # Fetch posts by user 3 using both methods.
+    fetch_posts_by_user_params_dict(3)
+    fetch_posts_by_user_url_string(3)
+
+    # Paginate through posts, 5 per page, 3 pages.
+    paginate_posts(page_size=5, num_pages=3)