A statistician trying to merge a player's domestic and international career records depends entirely on every record-keeper having used the exact same spelling of that player's name, every time. Nothing about a mismatched spelling looks wrong to a human watching a single match — everyone in the ground already knows who's batting — but it's a genuine, structural problem the moment anyone tries to combine those records automatically, because nothing in either record says the two entries refer to the same person unless someone manually cross-references them. An API with the same concept named two different things in two different endpoints has the identical problem: no single response looks wrong in isolation, and the cost stays invisible until something has to treat both endpoints as describing the same underlying thing.
Naming feels like the smallest decision in API design — pick a word, move on — which is exactly why it's the one most likely to be made inconsistently by a dozen different engineers over a dozen different weeks, each one making a locally reasonable choice that doesn't match the choice made two endpoints over. A style guide that exists only as an aspirational document doesn't fix this, because "be consistent" gives an engineer under deadline pressure nothing concrete to apply; a style guide that resolves real, specific disputes and is actually enforced does.
This lesson works through naming fields, booleans, and enums so a consumer can infer meaning from a name alone; what makes a style guide something engineers actually follow instead of a wiki page nobody rereads; and the mechanism — enforcement in CI, not a document — that's the only thing that reliably holds a naming convention in place as a team and its API both grow.
Analogy🏏Cricket
🏏 Think of it like cricket: A statistician trying to compile a single career record for a player who has turned out for a state team, a national team, and multiple franchise sides depends entirely on every one of those record-keepers having used the exact same name, spelled the exact same way, every time. A player recorded as "Suryakumar Yadav" in international scorecards and "S Yadav" in some domestic first-class records isn't a real ambiguity to a human watching the match — everyone in the ground knows exactly who's batting — but it's a genuine, structural problem for anyone trying to programmatically merge those two record sets into one, because nothing in either record says the two entries are the same person unless a human manually cross-references them. Statisticians who maintain a single, canonical spelling for every player across every record they touch, even when a specific scorer that day would have preferred a shorter or more familiar version, are the ones whose career databases can actually be merged, searched, and aggregated automatically years later. Just as a career database only works if a player's name is spelled identically everywhere it appears, an API only works if the same concept is named identically everywhere it appears — a `customer` in one endpoint and a `client` in another, meaning the exact same underlying entity, creates the identical structural ambiguity a misspelled player name does. Just as no single record looks wrong in isolation, no single inconsistently-named field looks wrong in isolation either — the cost only becomes visible the moment something has to be merged, searched, or handled generically across records that don't agree. The insight is that naming consistency isn't a cosmetic preference, it's what makes an entire body of records, or an entire API, addressable as one coherent thing instead of a pile of individually-fine records that don't actually connect.
🏏 Showing the Cricket analogy — a Cricket version isn’t available for this concept yet.