Skip to content

2026 07 14 Developer 0111

🎯 Session Summary

I played a five-quest window of the Software Developer path at Level 0111 (API Development, ⚔️ Adventurer tier) as a learner would: authenticate → handle errors → rate-limit → version → document. This is window 2 of 2 for the level (stats.window = index 1, offset 5, size 5 of a 10-quest level), so the two foundation quests it assumes — API Fundamentals and REST Principles — live in the previous window and were not walked here.

The machine evidence was pre-computed and sealed by the workflow in --mode execute (real sandbox, real commands); I consumed it as-is and did not re-run the engine. On top of that evidence I read all five quest sources in plan order to reason about the linked journey.

Headline verdict: ⚠️ warn. Engine average 77.4% (3 ✅ pass · 1 ⚠️ warn · 1 ❌ fail). The three middle quests (Error Handling 88, Rate Limiting 86, API Versioning 80) are solid and their runnable code executed exactly as written. The two bookends drag the slice down: API Authentication (76, warn) front-loads a $GITHUB_TOKEN command before teaching how to get the token, and API Documentation (57, fail) — the final quest of the level — has a non-existent redocly preview-docs command and a flagship Chapter 2 YAML example that fails redocly lint despite the text promising "a clean run." Those are the first things a maintainer should fix, because they hit learners at the very last gate of the API path.

🗺️ The Journey

# Verdict Quest Score One-line takeaway
1 ⚠️ API Authentication: Keys, Tokens, OAuth2, and JWT 76 Technically strong; PyJWT + base64 labs run clean, but $GITHUB_TOKEN is used before the quest says how to mint it, and "Token Storage" is an objective that's never taught.
2 ✅ Error Handling: Status Codes, Problem Details, and Retries 88 Accurate RFC 9457 / idempotency / backoff content; the retry client verified against local mocks. Only api.example.com curl examples are unresolvable and unflagged.
3 ✅ Rate Limiting: Token Buckets, 429s, and Quotas 86 Every runnable snippet (both Python labs, all three header-inspection curls) executed and matched the docs. Minor RateLimit-* vs X-RateLimit-* header-name mismatch.
4 ✅ API Versioning: URI, Headers, and Backward Compatibility 80 Live GitHub version-header + robustness-principle demos check out, but Chapter 2's two core api.example.com curls fail outright (domain doesn't resolve) with no "placeholder" note.
5 ❌ API Documentation: OpenAPI, Swagger, and Contract-First 57 Swagger UI + OpenAPI Generator work, but redocly preview-docs no longer exists and the Chapter 2 example fails redocly lint — the two things the quest tells a learner to run and trust.

🔬 Evidence

All statuses below come from the sealed walk-evidence.json (execute mode, real sandbox). The sandbox hard-blocks every curl invocation (even curl --version) and excludes sudo, so many network/curl steps are skipped — where the engine substituted an equivalent check (e.g. Python urllib against the real GitHub API), I note it. Steps judged only from the text are reasoned.

1. API Authentication — 76% · ran ⅝ runnable snippets

  • ✅ python3 -m pip install pyjwt (macOS & Linux) → installed pyjwt-2.13.0, no errors.
  • ✅ Chapter 2 PyJWT jwt.encode/jwt.decode → produced a 3-part token and printed user-42 read:profile on decode. Note: emitted an unmentioned InsecureKeyLengthWarning (the example secret is 24 bytes, < 32).
  • ✅ Chapter 2 echo "$JWT" | cut -d. -f2 | base64 -d → recovered {"sub":"user-42","scope":"read:profile","exp":1999999999}. Works here only because the payload length is a multiple of 4; arbitrary tokens may need base64url padding.
  • ✅ Cloud docker run … python:3.12-slim … pip install pyjwt → image pulled, PyJWT installed, valid JWT produced (verified via non-interactive equivalent; literal -it is correct for a real terminal).
  • ⏭️ All curl bearer-token calls skipped (sandbox curl block). Engine substituted urllib against https://api.github.com/user with a bad token → correct 401 Bad credentials, consistent with the quest.
  • 🧠 reasoned: the three api.example.com API-key curls and the OAuth2 token-exchange POST — intentional placeholder domains paired with YOUR_API_KEY/APP_SECRET; syntax is valid.

2. Error Handling — 88% · ran ⅜ runnable snippets

  • ✅ problem+json blocks (insufficient-funds + validation-errors) → valid, well-formed RFC 9457 documents.
  • ✅ Chapter 3 call_with_retry(url, max_attempts=5) → the retry/backoff/jitter logic verified to behave exactly as documented against local mock servers (retries only on 429/5xx, honors Retry-After, stops on 4xx).
  • ⏭️ httpbin status-code provocations and the Idempotency-Key POST skipped — sandbox blocks outbound curl/sudo/docker.
  • ⏭️ curl -s -i https://api.example.com/transfers/abc-123 | grep content-type skipped; api.example.com also does not resolve and isn't labeled illustrative-only.

3. Rate Limiting — 86% · ran 6/7 runnable snippets

  • ✅ curl -s -D - -o /dev/null https://api.github.com/rate_limit | grep -i ratelimit (macOS path) → real rate-limit headers returned.
  • ✅ curl -s https://api.github.com/rate_limit | jq '.rate' (Linux path) → live .rate object.
  • ✅ Chapter 1 TokenBucket class + demo → printed the documented [True×5, False, False] burst-then-reject pattern.
  • ✅ Chapter 2 curl … https://api.github.com/users/octocat | grep -i 'x-ratelimit' → GitHub's X-RateLimit-* headers observed.
  • ✅ Chapter 3 polite_get(url) client → runs; reads RateLimit-Remaining/RateLimit-Reset.
  • ✅ Cloud docker run --rm -it python:3.12-slim python → verified equivalent.
  • 🧠 reasoned: the illustrative HTTP/1.1 429 block showing IETF-draft RateLimit-* headers.

4. API Versioning — 80% · ran ⅞ runnable snippets (2 ✗)

  • ✅ macOS curl … -H "X-GitHub-Api-Version: 2022-11-28" … | grep api-version → live GitHub version echo.
  • ✅ Linux curl -s https://api.github.com/zen → live response.
  • ✅ Cloud docker run --rm curlimages/curl:latest … api.github.com/octocat → worked.
  • ✅ Chapter 1 curl -s https://jsonplaceholder.typicode.com/users/1 | jq '{id, name}' → the robustness-principle "ignore the extra field" demo runs live and returns exactly {id, name}.
  • ✅ Chapter 3 curl … | grep -i 'github-api-version' → deprecation/version-echo header observed.
  • ❌ curl -s https://api.example.com/v1/users/42 and /v2/users/42 → failed (domain does not resolve).
  • ❌ curl -s https://api.example.com/users/42 -H "Accept: application/vnd.example.v2+json" → failed (same). These are Chapter 2's core URI-vs-header demo and are not marked as placeholders.

5. API Documentation — 57% · ran 9 runnable snippets (5 ✗)

  • ❌ redocly preview-docs openapi.yaml → fails: command does not exist in current @redocly/cli (v2.39.0). Appears identically in all three OS setup blocks.
  • ❌ redocly lint openapi.yaml run in the setup block → fails: file does not exist — the setup section runs it before Chapter 1 ever creates openapi.yaml.
  • ❌ Chapter 2 Book paths+components example + its redocly lint → fails lint with 2 real errors despite the text saying "a clean run means tools can rely on it."
  • ✅ Cloud/Chapter 3 docker run … swaggerapi/swagger-ui → serves interactive docs as described.
  • ✅ Chapter 1 skeleton YAML (openapi/info/servers/paths:{}/components:{}) → valid.
  • ✅ Chapter 3 npx @openapitools/openapi-generator-cli generate -i openapi.yaml -g python -o ./client → generates a Python client as documented.

Sealed engine summary (verbatim from walk-evidence.md): "the quest is undermined by two confirmed, reproducible defects: redocly preview-docs does not exist in the current @redocly/cli … and the flagship Chapter 2 YAML example fails redocly lint with real errors despite the text promising 'a clean run.'"

🐞 Issues Found

High

  1. High · API Documentation · macOS/Windows/Linux setup blocks (lines ~152, 168, 181) · redocly preview-docs openapi.yaml — Confirmed by execute-mode run: the command does not exist in current @redocly/cli (v2.39.0), so it fails on all three platforms. Fix: replace with redocly preview (interactive) or redocly build-docs openapi.yaml -o docs.html (static).
  2. High · API Documentation · Chapter 2 "Validate the document with tooling" (lines ~256–309) · the Book example + redocly lint — Confirmed: the example fails lint with 2 errors, contradicting the promised "clean run." Fix: add a minimal security (or root security: []) so it lints clean, or tell the learner to expect and resolve a security warning.
  3. High · API Documentation · setup blocks run redocly lint openapi.yaml before any spec exists (lines ~152, 168, 181) — Confirmed file does not exist. A top-to-bottom reader runs lint in the setup section, but openapi.yaml isn't authored until Chapter ½. Fix: move lint/preview after the spec is created, or have the setup step scaffold a placeholder openapi.yaml first.

Medium

  1. Medium · API Versioning · Chapter 2 (lines ~248–260) · curl … https://api.example.com/v1/users/42, /v2/users/42, and the Accept: …v2+json variant — Confirmed failed (domain doesn't resolve) and, unlike the auth quest, these aren't paired with obvious YOUR_* placeholders or labeled illustrative-only. This is the chapter's hands-on centerpiece. Fix: add a one-line "api.example.com is illustrative — substitute a real host" note, or point the URI/header demo at a resolvable public API (as the quest already does elsewhere with GitHub / jsonplaceholder).
  2. Medium · API Authentication · "Choose Your Adventure Platform" (lines ~152, 167, 182) · curl … -H "Authorization: Bearer $GITHUB_TOKEN" — The token-minting instructions only appear far later, in the Novice Mastery Challenge (line ~339). A first-time reader hits an empty $GITHUB_TOKEN on the very first command. Fix: move the "create a GitHub personal access token" step up, or add a one-line pointer to the Mastery Challenge.
  3. Medium · API Authentication · Secondary objective "Token Storage" (line ~110) — Listed as an objective and mastery indicator but never taught in any chapter (no localStorage vs httpOnly-cookie vs in-memory discussion). Fix: add a short (3–4 sentence) token-storage paragraph.
  4. Medium · Error Handling · Chapter 2 (line ~277) · curl -s -i https://api.example.com/transfers/abc-123 — Same unflagged non-resolving api.example.com pattern as issue #4 (lower impact here — the curl is a small illustration, not the chapter's core). Fix: label api.example.com examples as illustrative-only.

Low

  1. Low · Rate Limiting · Chapter ⅔ header naming (lines ~263–283, ~305–322) — The 429 example and the polite_get client read IETF-draft RateLimit-* headers, but the live curl greps for — and GitHub actually returns — legacy X-RateLimit-*. A learner pointing polite_get at GitHub would find RateLimit-Remaining always defaults to "1". Fix: add one sentence noting many real APIs (GitHub included) still use the X-RateLimit-* names.
  2. Low · Rate Limiting · Secondary objective "Fixed vs Sliding Window" (line ~109) — Listed as a bonus objective but never covered in the body. Fix: add a brief comparison or drop it from the objective list.
  3. Low · API Authentication · Chapter 2 base64 decode (line ~280) — base64 -d works only because the example payload length is a multiple of 4; arbitrary JWTs may hit "invalid input." Fix: note base64url-without-padding. Also the PyJWT example's short secret triggers an InsecureKeyLengthWarning the quest doesn't mention.
  4. Low · API Documentation · "Contract tests" bonus objective (line ~344) — Mentioned as a concept but has no runnable example like the other bonus objectives. Fix: add one Schemathesis/Dredd invocation against the spec.

🔗 Chain Continuity

The slice holds together as a coherent API-design learning path. Walked in plan order, each quest's unlocks_quests cleanly feed the next, and the narrative arc ("The Gatekeeper's Road") reads as one journey: authenticate → fail gracefully → throttle → evolve → document.

  • Auth → Error Handling → Rate Limiting → Versioning → Documentation is a valid dependency-sorted order. Auth unlocks Error Handling + Rate Limiting; Error Handling unlocks Rate Limiting + Versioning; Rate Limiting unlocks Versioning + Documentation; Versioning unlocks Documentation — every forward edge in the window is satisfied by an earlier quest in the window.
  • Concepts genuinely compound. application/problem+json is introduced in Error Handling (Ch2) and then reused in Rate Limiting's 429 body (Ch2) — good reinforcement. Retry-After appears in both Error Handling and Rate Limiting with a consistent meaning. 410 Gone in API Versioning explicitly calls back to the status codes taught in Error Handling. This is the kind of cross-quest callback that makes a slice feel like a course rather than five isolated pages.

Prerequisite gaps (window-scoped, not curriculum bugs): Every quest here requires API Fundamentals and/or REST Principles, which live in window 1 of this level and were not walked in this session. A learner arriving from window 1 would have them; a learner dropped straight into window 2 would be missing the HTTP-headers/status-codes and resource-URL grounding all five quests assume. This is expected windowing behavior (stats.window index 1 of 2), not a defect — flagged only so the ledger records that the two foundation quests still need a walk to certify the level perfect.

Where a real developer-class learner would get stuck: - First command of the whole path (Auth setup) fails silently with an empty $GITHUB_TOKEN (issue #5) — a rough first impression at the entry to the level. - The final quest is the weakest link. After four mostly-smooth quests, a learner reaches API Documentation, copies redocly preview-docs, and it errors out — then the Chapter 2 example they're told will lint "clean" throws two errors (issues #1–#3). Ending the level's capstone on broken tooling is the highest-impact continuity problem in the slice, because it's the last thing the learner does before "advancing to Level 1000." - The api.example.com inconsistency (issues #4, #7) is a cross-quest smell: the Auth quest pairs the placeholder domain with obvious YOUR_API_KEY-style tokens so it reads as illustrative, but Versioning and Error Handling use the same domain in bare, copy-pasteable curls that fail — a learner who succeeded with the live GitHub calls will reasonably expect these to work too.

🧠 Reasoning & Method

  • Mode: execute — but I did not run the engine. The evidence (walk-evidence.json / walk-evidence.md) was pre-computed and sealed by the workflow in a disposable sandbox; per the skill, step 2 was already done and I consumed it verbatim. I made zero edits to walk-plan.json or walk-evidence.*.
  • What I ran vs. reasoned: All passed/failed/skipped statuses are the engine's real sandbox results, quoted from the sealed evidence — I did not re-derive or invent any. My own contribution (§Chain Continuity and the cross-quest framing of issues) is static reasoning from reading the five quest sources in plan order; where I lean on a step that was not executed, it is labeled reasoned and the cross-quest observations are grounded in exact quoted lines.
  • Coverage & caps: 5 of the level's 10 quests were in scope (window 2 of 2); I walked all 5. Snippet coverage per the engine: Auth ⅝, Error Handling ⅜, Rate Limiting 6/7, Versioning ⅞, Documentation 9 runnable (5 ✗). The lower coverage on Auth and Error Handling is driven almost entirely by the sandbox-wide curl block and sudo/docker exclusions, not by broken content — where curl was blocked the engine cross-checked HTTP semantics with urllib/local mocks, which I've reflected as skipped (verified via equivalent) rather than passed.
  • Limits of this pass: Network-restricted sandbox (no outbound curl; live checks reached only GitHub/jsonplaceholder via the engine's substitutions). The two foundation quests (API Fundamentals, REST Principles) were out of window and not walked. This is a real execute-mode walkthrough, not a --mock run.
  • Confidence: High on the two API-Documentation redocly defects and the Versioning api.example.com failures — those are reproducible commands that actually errored in the sandbox. Medium on the sequencing/completeness issues (Auth token ordering, unfulfilled objectives), which are text-level observations a maintainer can verify by reading the cited lines. No content was modified; every fix lives in the Issues section for a separate content pass to act on.