8. Chapter review

API documentation is often incomplete, outdated, or misleading. Exploration with explore_api_structure reveals the actual response shape (nesting patterns, field names, data types) that your code must handle. It surfaces variations that documentation might not mention (like Guardian's optional fields object) and produces a comparison table that drives every normalizer design decision.

A canonical model is one internal representation that all external formats are normalized into. The Article dataclass defines how articles are represented internally, regardless of whether they came from NewsAPI, Guardian, or HackerNews. Every downstream feature (display, storage, deduplication, sorting) works against one predictable structure instead of branching on source. Without a canonical model, every feature ends up needing conditional logic for each API.

Every normalizer: (1) extracts the items array using extract_items_and_meta(), (2) loops through each item with error containment via try/except, (3) validates required fields and skips items missing them, (4) maps API-specific field names to canonical names, and (5) constructs Article objects. The function returns the article list paired with a meta dict carrying per-response bookkeeping (total available counts) the aggregator uses for diagnostics. The five-step structure is identical across normalizers; only the field access patterns change.

Graceful degradation means the system continues operating with reduced functionality when components fail. When one API is down, the aggregator returns results from the working sources instead of crashing. Production systems face unpredictable failures (network issues, rate limits, API outages); users prefer partial results over error messages. The pattern requires independent failure handling per source, error categorization, and success/failure tracking.

Defensive programming prevents crashes by handling missing fields, type errors, and structural variations. It asks "will this crash?" and uses defaults, try/except blocks, and safe navigation. Validation enforces quality standards by rejecting data that doesn't meet requirements. It asks "is this acceptable?" and applies rules like "titles must be non-empty" or "timestamps must be valid ISO 8601." Defensive code accepts an article with an empty title (no crash); validation rejects it (violates quality standard). Chapter 12 builds the validation layer on top of the defensive layer this chapter taught.

continue lets batch processing proceed despite individual failures. If one article in a 50-article response has a missing title, you want the other 49 valid articles, not an exception that aborts the entire batch. The normalizer logs the issue and continues; the failure is contained to that item. Exceptions would be appropriate only if the entire response is fundamentally broken.

Defensive programming cannot prevent: empty required fields (an empty string is present, just useless), malformed timestamps (looks like a string but fails to parse), invalid URLs (non-empty but not actually a URL), quality degradation from defaults ("Unknown Source" everywhere), and business rule violations (future-dated articles, decades-old content surfacing as "fresh news"). These issues occur because defensive code only checks type and presence, not semantic validity. The data is technically correct but practically useless.

Without normalization, formatting code branches on source: "if NewsAPI then publishedAt, if Guardian then webPublicationDate, if HackerNews then convert created_at_i". With normalization, every Article has the same structure, so format_article and display_results never branch on source; they ship in a few dozen lines because all the variation got absorbed by the normalizers. That separation is the canonical model's most visible payoff: the canonical-model thesis from Q2 cashing out at the user-facing edge.