"""
GLAMWalk -- Volume 4: Libraries & Archives
14_cross_reference_only_pattern.py

The general shape every cross-reference-only integration in this book follows.

Source: Volume Four, Section 7.2 -- The Shared Pattern
Targets Python 3.11.4 -- see Volume One, Chapter 1.5/1.6.

NOTE: This is a teaching example. Some names stand in for something
you'd supply yourself when adapting the pattern to a real script.
"""

import requests


def extract_record_url(data):
    """Stand-in for real per-source parsing -- the JSON shape varies by
    source; this shows the return contract: a URL, or None."""
    return data.get("recordURL") or data.get("url")


def cross_reference_check(source_name, query_params, api_url):
    """
    Confirm a matching record exists, return a link a human can visit,
    and NEVER attempt to bulk-fetch or store the target's content.
    """
    response = requests.get(api_url, params=query_params, timeout=15)
    response.raise_for_status()
    return extract_record_url(response.json())