The application programming interface, or API, is what makes any software usable by other programmers. Companies like Google and Yahoo all make APIs that they give out for free to the public so people can make new software programs that use the companies services. They do this all so their name stays fresh in people’s minds and so when the next “hot” web application is released it will be using their base product.
APIs are literally the commands programmers have to type in to access the vendor’s software. For example, lets say you want to display a marker on a Google map. The API call for that action might be named displayMapMarker() - the programmers have to type this in their own application to do what they want.
As a developer that makes inhouse software, I never really considered what I do making APIs, but after reading some articles and talking to some people at work, it turns out I am creating APIs. But instead of making APIs for public consumption, I’m making them for myself.
Now you might think, as I did, with only being a one-man department I wouldn’t need to work hard at creating a generic API for anything. Afterall, if I made it and I’m the only one that’s going to use it, I know what to do, right? This is true…for about two months…or however long it takes to get the project done. After that, much like college, I flush the toilet in my head and all the stuff I needed to know for the time being is gone. Of course the downside to this method is when you have to go back to your project, because guess what, you forgot why you did what you did!
For this fact alone, it is important that you create a nice generic API for your own applications. You need to create API calls that describe what the call does so that you don’t really have to think too hard about what you’re going to get when you make that call.
This common sense didn’t hit me until recently when I had to go around updating a lot of old software. I had to re-learn everything about the programs and wasted a lot of time. I had the mentality of, “these are functions that no one will see so I can name them anything I want and it really doesn’t make a difference.” Wrong.
It’s as simple as this: Just describe what the call does. Literally.
If the call calculates the sum of accounts, your call should be called sumAccounts(). Or if you have a call that gives you a user’s e-mail address, it can be called getUserEmail().
I have gotten into the habit of going just a wee bit further by making the description include the primary parameter the call needs to work properly. So if the function that gets the user’s e-mail address requires you give it an ID number to work, then the call should be named getUserEmailById(). Up front this tells me what the call needs so I don’t even have to read the docs or notes or anything. Yay!
The amount of effort you save by naming your API calls this way is almost unmeasurable. You don’t need to get creative with your API calls. And don’t get all nerdy and come up with “cool” names for your API calls that sound good and look good to you, but really don’t mean anything.
By following this guideline, if other programmers ever do need to use your API the simple naming is already done! Help yourself and help others without any extra effort.
