Why API naming conventions matter, and how to master the art

What's in a name?

The name of an API is particularly important, Geewax says, since the functionality of an API so often depends upon the ability of its users to interact with it. Users regularly rely on API names to quickly discern what kind of information they are going to receive, view or manipulate when they access that API. Those names can also serve to indicate which APIs within a portfolio are directly related to each other or are designed for certain kinds of requests.

In the third chapter of his book, where he discusses the importance of API naming techniques, Geewax says the following:

With traditional compiled code, the names of our functions and variables are only important to those who have access to the source code, as the name itself generally disappears during compilation (or minification) and deployment. When designing and building an API, the names we choose are much more important, as they're what all the users of the API will see and interact with.

Click the cover and use code
'nltechtarget21' to receive a
35% discount when you buy
the book.

Another thing Geewax stresses is the importance of nailing down an API naming pattern early in the development process, if not first thing. The names developers choose to use upfront will set expectations when it comes to API naming practices, and ultimately influence how an API portfolio gets managed down the line. For instance, the specific names used for a certain API will affect what names developers can use when performing version updates or adding new APIs as new needs arise. And the larger an API portfolio becomes, the harder it is to alter names without rippling consequences.

API names: The good vs. the bad

The naming practices Geewax proposes in API Design Patterns essentially revolve around a central theme: There is a right and wrong way to identify APIs. A good API name should reduce redundancy and minimize user confusion. A bad name, however, can cause users to be misled or misinformed, make important APIs hard to find and, at worst, lead to redundant build efforts that siphon critical application resources and impose unnecessary development costs.

One example Geewax provides is that of an API designed to store user account preferences. If a developer were to simply name the API Preferences, it's likely the user wouldn't have enough context to understand what this API is or what it does. In that case, something like UserPreferences might be a better fit, as now the user can see exactly what they're dealing with.

On the other hand, getting too specific isn't good either. Suppose a developer named the same API mentioned above something like SingleUserAccountPreferences, it might confuse people as to whether this API stores the individual preferences of many users, or just the preferences of one individual user. If interpreted as the latter, it might even cause development teams who inherit the portfolio to think they need to build an API for each individual account. Once again, the simplicity of UserPreferences seems to serve best.

API name characteristics

When it comes to naming APIs, developers do have a little flexibility, since naming conventions aren't held to the same strict syntactical and structural demands of programming code. However, flexibility doesn't mean anything qualifies as an appropriate name.

When there are multiple ways to express the same thing, we often tend to use them interchangeably, which ultimately makes our naming choices unpredictable, and results in a frustrating and cumbersome API. To avoid some of this, even though 'language' has quite a bit of flexibility, by imposing some rules of our own, we can avoid losing the predictability we value so highly in a good API.

Of course, the right balance of clarity and simplicity will vary from project to project, making it hard to apply any kind of blanket rule. To provide some guidance, Geewax proposes the following three characteristics that a name should embody in order to align with practical API design principles:

• expressiveness, which means an API's name should clearly convey the type of function, resource, message, field, property or value that it represents;
• simplicity, which dictates that names should be expressive, but only to the extent that each part of the name adds a justifiable value; and
• predictability, meaning API names should be easy to learn and follow a recognizable naming pattern.

So, how do developers ensure that API names satisfy all three of these qualifications? To that end, Geewax identifies four general areas of concern when it comes to naming APIs appropriately.

• Consider using American English. While there will certainly be exceptions, it's typically preferable to name APIs using American English, as it is the most globally recognized language in the programming world. It's always possible to include localized documentation, if need be.
• Don't ignore proper grammar. While it's tempting to ignore grammar in favor of simplicity, proper grammar rules should still apply to API names. Use correct spelling and pay close attention to the appropriate use of singular versus plural nouns. This will help to accurately express the API and mitigate the risk of user confusion.
• Pay close attention to syntax. Syntax will dictate the established arrangement of words in an API's name. In most development shops, syntax is handled in one of three standard formats: camel, snake and kabab.
• Make sure to include context. An API name should ideally provide some indication of the framework or program type it's associated with. If the name of the API could mean different things in different scenarios, think about adding context to make the name more expressive.

To learn more about the API naming conventions and techniques discussed above, access this complimentary excerpt of the book's third chapter for an in-depth look at the associated strategies and best practices. Learn more about the book, including purchasing options, by visiting the publisher's page.