A Good API – Find Out What defines its Popularity?
With the current glut of APIs out on the market, it can be difficult to decide which would be best to use in any given scenario. If an API is to have a fighting chance at standing out from the crowd, then the excellent design is an absolute must. However, this begs the question: what makes for a good API in the first place?
Though some may believe this to be subjective, there are a few common characteristics shared by good APIs:
Characteristics of a Good API
1. Simple to Use
There is nothing inherently wrong with complexity in and of itself. After all, an API can contain several moving parts without being convoluted or messy, if done correctly.
However, many designers make the mistake of adding too many moving parts in a bid to provide as many options as possible. Despite their good intentions, this often ends up confusing rather than helping the end-user.
In this case, complexity is not the enemy. Rather, what developers should avoid is the confusion that can result from an API with an overly complicated code.
When it comes to APIs, less is more. Hence, a good API doesn’t add additional parts for a false sense of complexity. Rather, a well-designed API takes one complex part and breaks it down into several simpler parts. Some developers are able to pull this off using an API Design, Planning & Modeling Tool such as Stoplight, a tool that can help designers better visualize the final product. Another way to pull this off is by using abstraction layers. These are clear and easy-to-use interfaces that hide an API’s underlying complexity, providing users with clutter and distraction-free interface.
2. Consistent and Predictable
There is nothing more frustrating than an API that seems to function in unpredictable ways. Whether due to inconsistent labeling or nonsensical naming decisions, an API that behaves differently than expected can result in much frustration for the end-user.
On the other hand, a well-designed API strictly follows a common style throughout the whole code. It does not switch terms around unnecessarily. For instance, “users” would always be referred to as “users,” and would not be unexpectedly switched to “customers” without warning.
The consistent design naturally leads to predictability, another important characteristic of a well-designed API. Naming should also make logical sense so that the end-user can figure things out intuitively. For instance, “open” and “close” are opposite actions. Should an API have an “open” label, the user should be able to predict the opposite action, which would be “close.” On the other hand, using an unrelated word, such as “eliminate” would not come easily to any user.
3. Easy to Pick Up
An API will only be adopted by users if it is not difficult for them to figure it out. Hence, discoverability is crucial to a well-designed API.
To make an API discoverable is to make it so that even a complete beginner can easily pick it up and immediately integrate it into their project. One way to do this is to create self-describing access points. This is basically naming things so that they do exactly what they say on the label, so to speak. For instance, a user can immediately deduce what a method called “AddProductToCart” means compared to, say, “+ProdCart.”
While a user can try to work everything out on their own, they may still run into an issue that they can’t troubleshoot on their own. In these cases, adequate documentation can help users solve the problem without having to reach out to customer support, resulting in more quick and efficient coding.
Summary
Overall, a good API is one that can provide end-users with a hassle-free experience. Simplicity, clarity, consistency, predictability, and discoverability are only a few of the defining characteristics that developers should strive for. With a critical eye and proper planning, though, this ideal will be well within reach for any designer.