Unit 01.00: What an API is for, and when it is the wrong shape

An HTTP API is worth its cost when something outside your process needs to call you. Inside one process, an import is better in every respect.

Six situations, two of which are not APIs

The test is whether a network boundary is genuinely needed - another service, another language, a browser.

The code sorts six situations.

SHAPES = [
    ("another service needs this logic",        "API",       "network boundary needed"),
    ("a script you run yourself once a week",   "script",    "no caller but you"),
    ("a browser needs to fetch this",           "API",       "HTTP is the interface"),
    ("one function used across three files",    "import it", "same process"),
    ("a scheduled job writing to a database",   "job",       "no request, no response"),
    ("a colleague wants your model's predictions", "API",    "language-independent"),
]
print(f"{'situation':44} {'shape':10} why")
for situation, shape, why in SHAPES:
    print(f"{situation:44} {shape:10} {why}")

apis = sum(1 for _, s, _ in SHAPES if s == "API")
print(f"\n{apis} of {len(SHAPES)} genuinely need an HTTP boundary")

# An API is worth its cost when something outside your process needs to call
# you -- another service, another language, a browser. Inside one process, an
# import is faster, typed, and cannot return a 500.

The fourth row is the one that gets built as an API unnecessarily. A function used across three files in the same codebase should be imported: it is faster, it is type-checked, and it cannot return a 500.

The scheduled job is the other one. It has no caller and no response, so wrapping it in an endpoint adds a web server to something that needed a cron entry.

The mistake this prevents

The mistake is building an API because it feels like the professional shape. Each endpoint is a public contract, a deployment, a monitoring target and a security boundary - all of which are real costs paid continuously.

Takeaway

Build an API when something outside your process must call you. Within one process an import is faster, typed, and cannot fail over the network.

Mark complete