Dave Donaldson

Here's an API quiz for you. Which is better: A method named LoginUser() or Login()? What about GetUserProfile() or GetProfile()?

Now imagine I told you these methods lived in a class named Users. What's your answers now?

API design is all about the ease at which developers can make use of a given library, module, class, interface, method, etc, etc. A well-designed API doesn't require hours upon hours of reading through help files to understand how to use it. The best APIs provide most of what a developer needs to know right up front, in its signature. Good APIs also take into consideration the context in which they are used.

For example, let's look at my Users class mentioned above and the methods in it. Let's say I'm the API designer and you are the developer who needs to use my Users class. To execute login functionality, which option below is preferred by you:

1. Users.LoginUser(user, pswd)
2. Users.Login(user, pswd)

You can easily argue that both are valid and that both are clean. And I would agree, except #2 is cleaner and more succinct. Why? The Login() method is in a class named Users (its context), so when you call the Login() method, don't you already know that you're logging in a user? Wouldn't that make LoginUser() a little redundant in a class named Users? Yes it would.

The point here is that good API design is not easily done, even for a simple example as this. APIs are just like code - they need to be constantly tweaked and refactored to get them just so. API design is rather interesting because it blends technical know-how with psychology; it takes into account the cognitive understanding of the consumers of the API. And the 80-20 rule might be more true in API design than anywhere else in software development because of that fact.