An API defines how other programmers will interact with your software. As any coder write code, need to ask himself about the user of that code. If that user interacts with his code via code of their own, he is building an API. And before he asks, yes, that even applies to other developers in his company or even his team that uses his code.

So understanding the properties of good APIs carries a vital importance in software industry. Some characteristics of good APIs are:

1. Simplicity

First and foremost is simplicity. Developers tend to solve complex problems, making it easy to let that complexity bleed through to users of our APIs. Keeping them simple is not an easy task requires work, and sometimes presents a serious challenge.

Every developer tendency is to want to be helpful adds to the difficulty. Often, developers want to offer several different ways to do something. “Maybe they want to pass these dependencies in through a constructor. But what if they prefer to use setters? We should make both available.” The road to complexity can be paved with good intentions.

So it is fighting the urge to add undue complexity, even when you think it might help. Good APIs offer simplicity, and it requires a good bit of effort to preserve that simplicity.

2. Provide Useful Abstractions

Next, is the concept of abstraction. When developers successfully hide details from users of his API, leaving only the essentials, he offers them abstraction.

Abstraction examples are abundant in our world. Device drivers abstract the details of dealing with vendor hardware. Threading models provide an abstraction for worrying about scheduling execution at the OS level. The OS itself provides an abstraction over the differences in core computer hardware. Even your programming language abstracts away the details of writing machine code.

Well written code provides abstractions, and APIs are no exception. For any developer API should hide the details of what it does from users while making itself useful to them. If users need to dive into developer’s code or execution to understand, developers have provided a poor abstraction.

3. Discoverable

Simplicity and good abstractions will take you a long way. But you can go even further when you write a “discoverable” API. This has to do with how easily a novice can become productive using your code.

Strive for this with your APIs. Understand that your users will hack and experiment before they ever pick up a manual or call to ask. Plan and design accordingly, both with documentation/examples and with the sort of self-describing access points that lend themselves to discoverability.

4. Consistent and Symmetrical

Examine your API for consistency and for symmetry. Consistency is relatively easy to understand. Don’t call them “users” sometimes and “customers” at other times. Name the same things the same way. Have a common style. Make your API predictable.

Symmetry presents a slightly more subtle consideration. When we talk about symmetry, I mean a tendency to close open loops in a way that your users expect. For example, if you have an API for file access that lets you call Open(string filename), you should also offer a Close(string filename method). Open and close have opposite meaning, so offering both creates symmetry as concerns that operation. Calling the Close method “Destroy” or, worse, not having a close method, would create a great deal of confusion.

You can generally achieve this characteristic in your API by applying a critical eye to what you expose to users. Read through it the way a proofreader might, checking for consistency and symmetry. Then rename and alter as needed.

5. Follow the Principle of Least Astonishment

For the last consideration in the mix, I want to introduce you to the cleverly named “principle of least astonishment.” This holds that “a system should behave in a manner consistent with how users of that component are likely to expect it to behave; that is, users should not be astonished at the way it behaves.” To put it more bluntly, don’t write APIs that flabbergast your users.

Good APIs do not have properties that cause their users to exclaim, “but that makes no sense!” or “how would I ever have known that?!” I can think of no faster way to lose the trust of your users than to present them with an API that does something tangential to or opposite of what it claims to do.

6. Think of Your API as product

Simple, useful, discoverable, consistent, and predictable all describe not only good APIs, but good products. That’s no accident. When you write APIs, you create a product. Whether you think of it that way or not and whether you actually sell it or not, you have a product on your hands, intended for use by someone else.

As developers, we can easily lose sight of that. Subject to the curse of knowledge, we assume that our API users, fellow programmers, will know what we know and figure out what we’ve figured out. We don’t naturally think of them as our end users or our customers.

Overcoming that tendency and putting ourselves in their shoes is the unifying theme behind good API design. So when you write your next API, put yourself in the shoes of your customer, and imagine what you would want.