Hands-on lab — Day 18: HTTP: Requests, Responses, and Methods

#!/usr/bin/env bash
# Day 018 lab — Speak HTTP by Hand (reference implementation).
#
# Sends real HTTP requests with curl against free public test services and
# reads the raw request/response. Degrades gracefully:
#   * OFFLINE  -> skips the live requests, explains what each WOULD show, exits 0.
#   * httpbin.org busy (it is a shared free service and sometimes returns 503)
#     -> automatically falls back to its compatible mirror httpbingo.org so the
#        POST-echo and 404 demos still work.
#
# Run from the lab directory:
#   bash examples/http_explorer.sh
set -u

GOOD_URL="https://example.com"          # reliable, only serves GET/HEAD
HTTPBIN="https://httpbin.org"           # canonical test service (per the lesson)
HTTPBIN_MIRROR="https://httpbingo.org"  # compatible mirror, same JSON echo shape

hr() { printf '%s\n' "------------------------------------------------------------"; }

# Return a base URL for the echo/status demos: prefer httpbin.org, fall back to
# its mirror. We verify with the ACTUAL POST echo (not just a GET probe),
# because these shared free services sometimes answer GET while the echo still
# fails under load. Returns "" if neither host echoes right now.
pick_echo_service() {
  local base body
  for base in "${HTTPBIN}" "${HTTPBIN_MIRROR}"; do
    body="$(curl -s -X POST -H "Content-Type: application/json" -d '{"hello":"world"}' --max-time 10 "${base}/post" 2>/dev/null)"
    if printf '%s' "${body}" | grep -q '"hello"'; then
      printf '%s' "${base}"
      return 0
    fi
  done
  printf '%s' ""
}

# Network gate: a quick, time-limited request to a rock-solid host.
online="no"
if curl -s -o /dev/null --max-time 8 "${GOOD_URL}"; then
  online="yes"
fi

echo "=== HTTP Explorer ==="
echo "Network reachable: ${online}"
hr

if [ "${online}" != "yes" ]; then
  echo "OFFLINE MODE — no network reachable, so the live requests are skipped."
  echo "When online, this script would show you:"
  echo "  1. curl -v ${GOOD_URL}"
  echo "     -> your request lines (>) and the response's 'HTTP/.. 200' status line (<)."
  echo "  2. curl -s -o /dev/null -w '%{http_code}' ${GOOD_URL}"
  echo "     -> the bare status code 200, with the body thrown away."
  echo "  3. curl -X POST -H 'Content-Type: application/json' -d '{\"hello\":\"world\"}' ${HTTPBIN}/post"
  echo "     -> a JSON body echoing your payload back in its \"json\" field."
  echo "  4. curl -s -o /dev/null -w '%{http_code}' ${HTTPBIN}/status/404"
  echo "     -> the status code 404, produced on purpose."
  echo "=== End (offline) ==="
  exit 0
fi

# 1. Verbose: see BOTH messages. Request lines start with '>', response with '<'.
echo "STEP 1 — curl -v ${GOOD_URL}"
echo "(Request lines start with '>', response headers with '<'.)"
# -s hides the progress meter; 2>&1 merges curl's verbose stream (stderr) so we
# can filter it. We show only the request/status/header lines, not the HTML body.
curl -s -v "${GOOD_URL}" -o /dev/null 2>&1 | grep -E '^[<>]' | head -n 16
hr

# 2. Read ONLY the status code. -o /dev/null discards the body; -w prints the code.
echo "STEP 2 — status code only for ${GOOD_URL}"
code="$(curl -s -o /dev/null -w '%{http_code}' "${GOOD_URL}")"
echo "Status code: ${code}"
hr

# Choose the echo/status service for steps 3 and 4.
ECHO_BASE="$(pick_echo_service)"
if [ -z "${ECHO_BASE}" ]; then
  echo "NOTE: both httpbin.org and its mirror are busy right now (a shared free"
  echo "service, so this happens). Steps 3-4 are skipped; rerun in a minute."
  echo "The GET checks above already succeeded, so your network and curl are fine."
  echo "=== End of HTTP Explorer ==="
  exit 0
fi
echo "Using echo service: ${ECHO_BASE}"
hr

# 3. POST a JSON body and watch the service echo it back.
echo "STEP 3 — POST a JSON body to ${ECHO_BASE}/post"
echo "Request body sent: {\"hello\":\"world\"}"
echo "Server echoed the 'json' field back as:"
curl -s -X POST -H "Content-Type: application/json" -d '{"hello":"world"}' "${ECHO_BASE}/post" \
  | grep -A2 '"json"'
hr

# 4. Trigger a 404 on purpose so a failing status becomes information, not alarm.
echo "STEP 4 — deliberately request a 404 from ${ECHO_BASE}/status/404"
code404="$(curl -s -o /dev/null -w '%{http_code}' "${ECHO_BASE}/status/404")"
echo "Status code: ${code404}  (4xx = client error: the resource was not found)"
hr

echo "=== End of HTTP Explorer ==="

lesson_id: D018
day: 18
kind: api-example
languages: [bash]
setup_commands:
  - cd labs/sections/computing-foundations/day-018-http-requests-responses-and-methods
run_commands:
  - bash examples/http_explorer.sh
  - bash starter/http_explorer.sh
test_commands:
  - bash tests/run_tests.sh
cleanup_commands:
  - 'git checkout -- starter/http_explorer.sh starter/http-worksheet.md  # optional: reset your work'
requires_network: true
requires_api_key: false
estimated_minutes: 30
last_executed: '2026-07-12'
executed_on: 'macOS (curl 8.7.1), bash tests/run_tests.sh -> 7 checks, 0 failure(s), 0 skip(s)'

# Dependencies — Day 018 lab

**Just `curl`, which is already installed.** This lab has one tool dependency
and it ships with your OS:

- `curl` — the command-line HTTP client. Preinstalled on macOS and on every
  mainstream Linux distribution. Check with `curl --version`.
- `bash` ≥ 3.2 and the standard `grep` — also part of the base system.

If `curl` is somehow missing (rare, or a minimal container), install it with
the Day 13 package manager:

- macOS: `brew install curl`
- Debian/Ubuntu: `sudo apt install curl`
- Fedora: `sudo dnf install curl`

**Optional:** HTTPie (`http`) is the friendlier client shown in the lesson.
Install it with `brew install httpie` or `sudo apt install httpie` if you want
to try it — it is not required for any exercise or test.

There is no `requirements.txt`/`package.json`: the lab needs no language
runtime, only `curl` and a network connection.

#!/usr/bin/env bash
# Day 018 lab — Speak HTTP by Hand (YOUR working file).
#
# Complete the FOUR numbered exercises below by replacing each
#   : "EXERCISE n — ..."      (a no-op placeholder line)
# with the exact curl command named in its comment. The finished reference
# version is in examples/http_explorer.sh — run that first to see the goal.
#
# Run from the lab directory:
#   bash starter/http_explorer.sh
set -u

GOOD_URL="https://example.com"
HTTPBIN="https://httpbin.org"

echo "=== HTTP Explorer (starter) ==="

# A quick network gate so the script degrades gracefully offline.
if ! curl -s -o /dev/null --max-time 8 "${GOOD_URL}"; then
  echo "OFFLINE — no network reachable. Reconnect and rerun to do the exercises."
  echo "=== End (offline) ==="
  exit 0
fi
echo "Network reachable: yes"
echo "------------------------------------------------------------"

# ---------------------------------------------------------------------------
# EXERCISE 1 — See BOTH messages with the verbose flag.
#   Run:  curl -v https://example.com
#   Lines starting '>' are your request; lines starting '<' are the response,
#   beginning with the status line. (This prints the HTML body too — that's ok.)
echo "EXERCISE 1 — curl -v ${GOOD_URL}"
: "EXERCISE 1 — replace this line with: curl -v \"${GOOD_URL}\""
echo "------------------------------------------------------------"

# ---------------------------------------------------------------------------
# EXERCISE 2 — Read ONLY the status code.
#   Run:  curl -s -o /dev/null -w "%{http_code}\n" https://example.com
#   -s silences the meter, -o /dev/null throws the body away, -w prints the code.
#   You should see 200.
echo "EXERCISE 2 — status code only for ${GOOD_URL}"
: "EXERCISE 2 — replace this line with the curl -s -o /dev/null -w command above"
echo "------------------------------------------------------------"

# ---------------------------------------------------------------------------
# EXERCISE 3 — POST a JSON body and watch it echoed back.
#   Run:  curl -X POST -H "Content-Type: application/json" \
#              -d '{"hello":"world"}' https://httpbin.org/post
#   -X POST sets the method, -H adds a header, -d supplies the body (and makes
#   it a POST). Look for your data in the response's "json" field.
#   (If httpbin.org is busy and returns 503, retry, or use https://httpbingo.org/post.)
echo "EXERCISE 3 — POST a JSON body to ${HTTPBIN}/post"
: "EXERCISE 3 — replace this line with the curl -X POST ... command above"
echo "------------------------------------------------------------"

# ---------------------------------------------------------------------------
# EXERCISE 4 — Trigger a 404 on purpose.
#   Run:  curl -s -o /dev/null -w "%{http_code}\n" https://httpbin.org/status/404
#   The test service returns whatever status you ask for. You should see 404.
echo "EXERCISE 4 — deliberately request a 404 from ${HTTPBIN}/status/404"
: "EXERCISE 4 — replace this line with the curl -s -o /dev/null -w 404 command above"
echo "------------------------------------------------------------"

echo "=== End of HTTP Explorer (starter) ==="

# HTTP worksheet — Day 018

Fill this in by running `curl` yourself. Every answer comes from a command you
run in the terminal; copy the real values you see.

## 1. Status code of a normal GET

Command:

```bash
curl -s -o /dev/null -w "%{http_code}\n" https://example.com
```

- Status code returned: `__________`  (expected: a 2xx success)
- Which status class is that, and what does the class mean? `__________`

## 2. The Content-Type header of a page

Run the verbose request and find the `content-type` line in the **response**
headers (the lines starting with `<`):

```bash
curl -v https://example.com 2>&1 | grep -i "^< content-type"
```

- `Content-Type` reported: `__________`  (expected: `text/html`)
- In one sentence, what does `Content-Type` tell the client to do? `__________`

## 3. What httpbin.org/post echoes back for your POST body

Send a JSON body of your choosing (change the values if you like) and read the
`json` field of the response:

```bash
curl -s -X POST -H "Content-Type: application/json" \
     -d '{"hello":"world"}' https://httpbin.org/post
```

(If httpbin.org returns 503, retry once or use `https://httpbingo.org/post`.)

- The body you sent: `__________`
- What the `"json"` field of the response contained: `__________`
- Did the `headers` section of the response show the `Content-Type` you sent?
  `__________`

## 4. Short answer: 401 vs 429

In 4–6 sentences, explain why a `401` and a `429` require **completely
different** responses from your code. Name whose fault each is (client or
server), and say what you should do for each — for example, why retrying a
`401` unchanged can never succeed, while a `429` calls for slowing down.

```
____________________________________________________________________________
____________________________________________________________________________
____________________________________________________________________________
____________________________________________________________________________
```

#!/usr/bin/env bash
# Tests for the Day 018 lab. Run from the lab directory:
#   bash tests/run_tests.sh
#
# Structure checks always run. Network checks (a real 200 from a known-good URL
# and a real POST-body echo) run only when the network is reachable; offline
# they are SKIPPED with a clear message. The script exits 0 unless a check that
# actually ran failed.
set -u

lab_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
failures=0
checks=0
skips=0

GOOD_URL="https://example.com"
HTTPBIN="https://httpbin.org"
HTTPBIN_MIRROR="https://httpbingo.org"

check() {
  local label="$1" ok="$2"
  checks=$((checks + 1))
  if [ "${ok}" = "yes" ]; then
    echo "  ok: ${label}"
  else
    echo "  FAIL: ${label}"
    failures=$((failures + 1))
  fi
}

skip() {
  skips=$((skips + 1))
  echo "  skip: $1"
}

echo "Structure checks ..."
# The three scripts/worksheet the learner needs must exist and be non-trivial.
for f in "examples/http_explorer.sh" "starter/http_explorer.sh" "starter/http-worksheet.md"; do
  if [ -s "${lab_dir}/${f}" ]; then check "${f} exists and is non-empty" "yes"; else check "${f} exists and is non-empty" "no"; fi
done
# The example script must reference curl and the good URL.
if grep -q "curl" "${lab_dir}/examples/http_explorer.sh"; then check "example uses curl" "yes"; else check "example uses curl" "no"; fi
if grep -q "example.com" "${lab_dir}/examples/http_explorer.sh"; then check "example references the known-good URL" "yes"; else check "example references the known-good URL" "no"; fi

echo
echo "Network checks ..."
# Is the network up? Probe the rock-solid host with a short timeout.
if curl -s -o /dev/null --max-time 8 "${GOOD_URL}"; then
  # Check 1: a known-good URL returns 200.
  code="$(curl -s -o /dev/null -w '%{http_code}' --max-time 15 "${GOOD_URL}")"
  if [ "${code}" = "200" ]; then check "GET ${GOOD_URL} returns 200" "yes"; else check "GET ${GOOD_URL} returns 200 (got ${code})" "no"; fi

  # Check 2: a POST body is echoed back. Try the ACTUAL POST against httpbin.org
  # first, then its mirror — a GET probe can succeed while the echo still fails,
  # because these shared free services flap under load. Pass on the first host
  # that genuinely echoes the body. If NEITHER echoes, SKIP (a third-party
  # outage is not the learner's fault) rather than fail the suite.
  echoed="no"
  echoed_by=""
  for base in "${HTTPBIN}" "${HTTPBIN_MIRROR}"; do
    body="$(curl -s -X POST -H "Content-Type: application/json" -d '{"hello":"world"}' --max-time 15 "${base}/post" 2>/dev/null)"
    if printf '%s' "${body}" | grep -q '"hello"' && printf '%s' "${body}" | grep -q '"world"'; then
      echoed="yes"; echoed_by="${base}"; break
    fi
  done

  if [ "${echoed}" = "yes" ]; then
    check "POST body is echoed back by ${echoed_by}" "yes"
  else
    skip "POST echo — httpbin.org and its mirror are both busy right now; rerun later (network and GET are fine)"
  fi
else
  skip "network unreachable — 200 and POST-echo checks skipped (offline is fine)"
fi

echo
echo "${checks} checks, ${failures} failure(s), ${skips} skip(s)."
[ "${failures}" -eq 0 ]