Naming is where the domain model leaks. If your paths are /getUserDataV2 and /tblCustMaster, you
have told every consumer that this API is an export of an internal system rather than a designed
interface, and no amount of documentation recovers that first impression.
The rules that carry most of the value are boring. Use nouns for resources and let HTTP methods be the
verbs. Use plural for collections — /invoices/{id}, not /invoice/{id} — and be consistent about it
everywhere. Pick one casing convention for paths, one for query parameters, one for JSON fields, and
never mix. Spell words out; the four characters you save with cust cost every consumer a lookup.
The rule that carries the most value is the least technical: use the words the business actually uses.
If the company says “policyholder,” the resource is /policyholders, not /users. When the API’s
vocabulary matches the organization’s vocabulary, integration conversations get dramatically shorter,
and the API becomes legible to people who do not write code.
Then do the governance part. Write the naming convention into the style guide, encode it as linting rules, and run those rules in the editor and the pipeline. Naming is the single highest-frequency design decision in an API portfolio, which makes it the one most worth automating agreement on.
