Missing APIs Terms — AI Knowledge Base (Gap Analysis)

Purpose: This document is an input for an AI generation pass. It lists the terms that are used in the existing 04-apis/ prose but never defined as their own term, plus the relationships each missing term has to other missing terms and to existing terms. Every row is pre-shaped to drop directly into the curriculum's 8-section term template (Prerequisites → Category → Environment → Explanation → Common Mistakes → Exercises → Related Terms → Key Takeaways).

Scope reviewed: 50 existing terms across terms/level_01 … terms/level_10, plus _meta/apis_terms_zero_to_hero.md and _meta/technology_context.md.

Method: (1) Verified cross-link integrity — no broken ../level_XX/*.md links exist, so "missing" here means conceptual gaps (a concept appears in prose/code but has no term file), not dangling references. (2) grep-counted how many existing files lean on each undefined concept, to prioritize by blast radius.

---

0. Two structural findings the generating AI must know first

1. The Level 7 index no longer matches the files — RESOLVED by re-titling Level 7. _meta/apis_terms_zero_to_hero.md advertises Level 7 = "GraphQL Fundamentals" (GraphQL, Schema & Types, Queries, Mutations, Resolvers), but the actual terms/level_07/ files are a data-formats set: serialization.md, json_methods.md, xml.md, base64.md, graphql.md. Decision (adopted here): re-title Level 7 to "Data Formats & Serialization" so the index matches the files that already exist, and treat GraphQL as a single introductory term inside that level rather than a five-term sub-curriculum. The four GraphQL sub-terms (Schema & Types, Queries, Mutations, Resolvers) are therefore descoped — no longer counted as required gaps. They remain an optional future deep-dive, listed at the end of Section 2 for reference only.

   Exact index rewrite the generating AI must apply to _meta/apis_terms_zero_to_hero.md:

   ## Level 7: Data Formats & Serialization
   31. Serialization & Deserialization
   32. JSON Methods (parse / stringify)
   33. XML
   34. Base64 Encoding
   35. GraphQL (The REST Alternative)
   

   This maps 1:1 onto the five existing files and removes the contradiction.

2. No missing_terms.md tracker exists in _meta/ (unlike 03-javascript). When these terms are generated, create _meta/missing_terms.md to record them, mirroring the JavaScript knowledge base's tracker convention.

---

1. Critical gaps — concepts used everywhere but never defined

These block comprehension the most because existing terms depend on them in prose/code.

---

2. Missing terms by level

Each row: Proposed Term | description | Category | Prerequisites | Related. Categories follow the ones already used in this KB (Networking Protocol, Browser API / Networking, Data Format, Security, Architecture / Design, Real-Time, Tooling). 🆕 = brand-new concept.

Level 1 — Foundations of the Web (networking substrate under HTTP)

Per technology_context.md, keep these high-level mental models, not academic TCP/IP theory.

Level 2 — HTTP Anatomy

Level 3 — RESTful APIs

Level 4 — Security & Authentication

Level 5 — Fetching Data (Client-Side)

Level 6 — Advanced API Concepts

Level 7 — Data Formats & Serialization (re-titled to match existing files)

Existing files: serialization.md, json_methods.md, xml.md, base64.md, graphql.md. The gaps below deepen the data-format theme this level actually teaches.

Level 8 — Real-Time APIs

Level 9 — Browser APIs (Storage & State)

Level 10 — Designing & Tooling

Optional (descoped) — GraphQL sub-curriculum

Not required gaps. Because Level 7 is now "Data Formats & Serialization" (Section 0), GraphQL is a single term and these are an optional future deep-dive only. Generate them only if the curriculum owner later decides to expand GraphQL into its own dedicated level.

---

3. Relationship map (dependency graph)

Notation: A → B means "A requires / builds on B". Bold = existing term; plain = missing.

Cluster 1 — Networking substrate (new foundation under Level 1)

HTTPS ───────→ SSL/TLS & Handshake ──→ Certificate
**HTTP/HTTPS** → TCP/IP (high-level) → IP Address & Port → DNS
**URL/URI** ──→ DNS
**WebSockets** → TCP/IP (high-level)

Cluster 2 — Data format & serialization (glue across the whole KB)

Content-Type & MIME Types → **HTTP Headers**
   ├─→ **Request Body**        (declares payload format)
   ├─→ **Response Object**     (reads it back)
   └─→ FormData & Multipart Uploads
Content Negotiation (Accept) → Content-Type & MIME Types
URL Encoding → **Query Parameters**
**Serialization** → **JSON** / **XML** / **Base64** / Protocol Buffers
Storage Serialization → **Web Storage** + **Serialization**

Cluster 3 — CORS & browser security (currently a floating island)

**CORS** → Same-Origin Policy → Client-Server Model
**CORS** → Preflight Request (OPTIONS) → **HTTP Methods**
CORS Errors in the Browser → **CORS** + **fetch**
CSRF → **Cookies** + Session vs Token Auth
XSS → **JWT** + **Web Storage**

Cluster 4 — Auth token lifecycle

**OAuth 2.0** → OAuth Scopes
**JWT** → Access Token vs Refresh Token → Session vs Token Auth
Session vs Token Auth → **Statelessness**
Cookie Attributes (HttpOnly/Secure/SameSite) → **Cookies** → CSRF
Secrets & Environment Variables → **API Keys**

Cluster 5 — Network reliability (mandated by technology_context.md)

Request Timeout → **fetch**
AbortController → **fetch**
Retry & Exponential Backoff → **Error Handling** + **Rate Limiting**
   └─→ Idempotency Keys → **Idempotency**
Circuit Breaker → Retry & Exponential Backoff
Promise.all / Parallel Requests → **Promises** + **async/await**

Cluster 6 — Data formats & serialization (re-titled Level 7)

**Serialization** → Deserialization / Parsing
**Serialization** → Character Encoding (UTF-8) → Base64
Binary vs Text Formats → **Base64** / Protocol Buffers
Blob & ArrayBuffer → **Response Object** + **fetch**
Over-fetching vs Under-fetching → **REST** (the problem **GraphQL** solves)
   (optional deep-dive) **GraphQL** → Schema & Types → Queries / Mutations → Resolvers

Cluster 7 — Real-time deepening

WebSocket Handshake (Upgrade) → **WebSockets** + **HTTP Headers**
Heartbeat / Ping-Pong → **WebSockets**
Reconnection & Backoff → **WebSockets** + Retry & Exponential Backoff
Pub/Sub & Channels → **Socket.io**

Cluster 8 — Architecture & tooling (Level 10 breadth)

API Gateway → **Rate Limiting** + Load Balancing
Microservices vs Monolith → API Gateway
Load Balancing → **Statelessness**
API Contract / Schema-First → **OpenAPI** → Mocking
Deprecation & Sunsetting → **Versioning**
Protocol Buffers → **gRPC** + **Serialization**
SDK / Client Library → **API** + **fetch**
SOAP & XML-RPC → **XML**

---

4. Suggested generation priority

---

5. Notes for the generating AI

1. Follow the existing 8-section template exactly (see terms/level_05/fetch.md and terms/level_01/http_https.md): Prerequisites → Term Category → Environment Context → Explanation (Design Motivation / Reality Metaphor / Anatomy or Code Examples) → Common Mistakes & Pitfalls → Practice Exercises → Related Terms → Key Takeaways.
2. Obey _meta/technology_context.md: Senior Full-Stack Architect persona; pragmatic, security-conscious tone; async/await + fetch over XMLHttpRequest; keep networking internals (TCP/IP, handshakes) at a high-level mental-model depth, not academic theory.
3. Wire cross-links using the relative format ../level_XX/<file>.md, matching the Prerequisites/Related columns in Section 2. Every new term must be reachable from at least one existing term (add it to that term's Related section too).
4. Re-title Level 7 first (decision already made — Section 0). Replace the Level 7 block in _meta/apis_terms_zero_to_hero.md with the "Data Formats & Serialization" heading and the five entries listed in Section 0, so the index matches the existing files. GraphQL stays a single term; do not generate the four GraphQL sub-terms (they are descoped/optional).
5. Renumber consistently. Existing terms use # Term #N: headers. Decide whether new terms append after #50 or adopt level-relative numbering, and apply it uniformly.
6. Create _meta/missing_terms.md (it does not yet exist here) and record each generated term, mirroring the tracker convention in knowledge-base/03-javascript/_meta/missing_terms.md.
7. Environment tags must be one of the values already in use: Universal Web Standard, Client-Side (Browser), Node.js / Server-Side, or Both — pick per the term's reality (e.g. Same-Origin Policy = Browser; Load Balancing = Server; Content-Type = Universal).