Naming public vs internal APIs: what changes
Most companies run two kinds of APIs: the public one developers pay to use, and the internal ones stitching services together. Naming them by the same rules is a mistake — they have different audiences, different lifespans, and different jobs. Here is how the strategy splits.
The core difference: product vs plumbing
A public API name is a brand asset. It appears in marketing, in developers' code, in Stack Overflow questions, in conference talks. It needs to be memorable, ownable, and stable for years — renaming a public API breaks every integration built on it.
An internal API name is infrastructure. Its audience is your own engineers, who value clarity over charm: the name should say exactly what the service does and where it fits in the system. Internal names can and should evolve as the architecture does.
| Dimension | Public API | Internal API |
|---|---|---|
| Audience | External developers, buyers | Your own engineers |
| Goal of the name | Memorable, trustworthy brand | Instantly descriptive |
| Stability | Frozen for years | Can evolve with architecture |
| Style | Brandable, distinctive | Descriptive, systematic |
| Example | A named product ("Meridian API") | A descriptive label ("billing-service") |
Public API naming rules
- Brand it like a product. The name carries marketing weight — generate candidates with the API name generator and run them through the same checks as a product name: trademark, domain, pronounceability.
- Keep it abstract enough to grow. "Payments API" is fine until you add fraud, payouts, and invoicing. A brandable name survives scope creep; a literal one does not.
- Version in the contract, not the name. The product name stays constant while versions change underneath — see our naming conventions guide.
- One name, one promise. Do not ship three public APIs with overlapping names. Consolidate or differentiate sharply.
Internal API naming rules
- Describe, do not brand.
user-auth-servicebeats "Project Cerberus" — the next engineer to debug it at 2am will thank you. - Encode the domain, not the org chart. Name by business capability (billing, inventory, notifications), not by team ("team-blue-api") — teams reorganize, capabilities persist.
- Use a systematic scheme. A pattern like
{domain}-{capability}-{interface}lets engineers predict names they have never seen. - Allow renames. Internal consumers are your own code — refactoring tools make renames cheap. Do not let a bad internal name fossilize.
When the lines blur
Partner APIs, "public-but-limited" beta APIs, and APIs you plan to open later sit in between. The rule: name for the most public audience the API will ever have. It is cheap to give an internal API a decent brandable name up front; it is expensive to rebrand the thing partners already integrated with. When in doubt, choose the public-style name and keep the internal-style clarity in the endpoint paths. Once the API-level strategy is set, the endpoint paths need their own discipline — see our guide on API endpoint naming mistakes to get them right.
The graduation problem
The most common naming disaster: an internal API with an internal-style name ("svc-usr-mgmt-v2") gets opened to customers, and now your brand is a database table name. If there is any chance an API goes public, give it a real name from day one — or plan a deliberate rename before the first external consumer onboards, while the cost is still small.
Key takeaway: public names are brands — memorable, stable, ownable. Internal names are labels — descriptive, systematic, refactorable. Pick the strategy by audience, and name for the most public future the API might have.
The naming decision checklist
When a new API needs a name, run through these questions in order: (1) Will external developers ever see it? If yes, it needs the public treatment — brandable, trademark-checked, stable. (2) Does it describe a business capability that will outlive the current org chart? Name the capability, not the team. (3) Could it graduate from internal to public later? If there is any chance, give it the public-style name now — retroactive renames are where the real cost lives. (4) Does it collide with an existing API name, internally or in the market? Search both. (5) Can a new engineer guess what it does from the name alone? If not, the name is decoration, not communication. Generate candidates with the API name generator and score them against this list — the winner is usually obvious.
FAQ
Can an internal API name become public later?
Technically yes, but plan a rename before opening it up. External developers should never have to integrate with a name like "svc-usr-mgmt-v2".
Should internal APIs have versioned names?
Version the contract, not the service name. The service keeps its descriptive name while its API versions evolve — renaming services per version creates operational chaos.
How many public APIs should a company have?
Fewer than you think. One well-designed public API with clear resource boundaries beats five overlapping ones. Consolidate aggressively.
Do internal names need trademark checks?
Not usually, but do check for collisions with your own future public names — and avoid names that would embarrass you if they leaked (they will leak).
What about APIs shared with partners but not fully public?
Treat them as public for naming purposes: brandable name, stable contract, real documentation. Partners integrate like customers, not like colleagues.