Name the Role, Not the Vendor: Interface Naming as an Architectural Decision
Most naming debates are matters of taste and deserve about five minutes. A small number are architectural decisions in disguise, and they are worth considerably more, because a name that leaks into an interface becomes a constraint that outlives whatever it was named after.
The distinction is simple. Names inside a system can be changed by whoever owns the system. Names in an interface — a header, an environment variable, a service name, a config key — are contracts. Other systems depend on them. Changing one is a migration.
A concrete case
We needed a request header to carry a shared secret between a content management system and the front end consuming it. The obvious name borrowed the front-end framework's prefix: X-<Framework>-Revalidate-Secret. It was descriptive and it matched the surrounding ecosystem.
It was also wrong, and the reason is worth stating precisely: the header is not a property of the front end. It is the contract between the two systems. Naming it after one participant asserts that participant is permanent.
The alternative that first suggests itself — an organisation prefix, X-<Company>-Revalidate-Secret — is wrong in the same way, one axis over. It says the contract belongs to one tenant. For anything intended to be deployed for more than one client, that is the more expensive mistake, because it pins the interface to the first customer rather than merely to the first framework.
What shipped was X-Revalidate-Secret. It names what the header does. It survives replacing the front end, replacing the CMS, and deploying for a different organisation, because it never claimed anything about any of them.
The four axes
Names leak along four axes, and each one becomes a migration later:
- Vendor or framework — pins the interface to a technology choice. Replacing the technology now means either a migration or a name that lies.
- Tenant or client — pins it to the first customer. Every subsequent deployment inherits a name that refers to somebody else.
- Host or machine — pins it to one box. The system cannot move without either a rename or documentation that is quietly false.
- Environment — pins it to a stage. Names containing "staging" or "prod" tend to end up in the other one.
In each case the name was accurate when written. Accuracy is not the property that matters; durability is.
What must not be renamed
The rule has a boundary, and ignoring it does real damage.
Some framework-specific names are load-bearing. A build tool that only exposes environment variables carrying a particular prefix is not following a convention you can improve — that prefix is a functional requirement. Rename it and the value silently stops reaching the code that needs it, with no error.
Similarly, names owned by an upstream dependency are not yours. A module's configuration keys and package identifiers belong to that project. Renaming them locally is a fork.
So a naming sweep is never a find-and-replace. It requires sorting occurrences into three categories — ours and renameable, externally mandated, and descriptive prose — before changing anything. Prose describing the current implementation is fine; the rule concerns interfaces and identifiers, not pretending you use different technology than you do.
Renaming an interface safely
Interface names are runtime contracts, so the migration has the same shape as any protocol change:
- Teach the receiver to accept both names, preferring the new one. Deploy it alone. Nothing changes yet.
- Switch the sender in a later release.
- Remove the old name once telemetry confirms nothing uses it.
Done in that order, no deployment window exists where the two sides disagree. Done in the other order, there is a period where the sender emits a name the receiver does not know — and depending on the interface, that failure can be silent.
The same discipline applies to service names, environment variables and configuration keys, with the added complication that some carry state. Renaming a module's machine name in a content management system is not an edit; the old name is recorded in the database and in exported configuration, so it needs a migration path, not a text substitution.
Why it is worth the effort
The argument for role-based naming is not elegance. It is that the alternative charges interest.
A system built with vendor names in its interfaces can still be replatformed — it just costs a migration per name, each one requiring a transition window and coordinated deployments. A system built with role names replaces its front end without touching the contract at all.
The cost of getting this right is a few minutes of thought at the moment of naming. The cost of getting it wrong is paid later, by someone else, usually while doing something more urgent.