Common Usability Issues with Web APIs: And How Discovery Can ...

Today, I’ll be covering the most common usability issues that arise when developers start working with a new API. ... Customer-facing APIs are products. And just like any product, if we don’t do good discovery, we’ll have gaps in our offering. In this article, we’ll look at the following gaps that tend to arise with API products: - Inaccurate, incomplete, or insufficient documentation - Insufficient endpoint coverage or confusing endpoint design - Limited access to resources - Confusing error codes - Inadequate or confusing authentication options - Sloppy implementation of REST principles Before we dive into the details for each of these, I want to remind you why this matters. ... By far the most common challenge engineers face when working with a new API is inaccurate, incomplete, or insufficient documentation. Remember, an API defines a pre-defined language for how code can interact with another service. If that language is not well documented, then engineers won’t know how to construct requests or interpret responses. … Sadly, the former is far more common. Even when developers set out to define clear error codes, the curse of knowledge often comes into play. ... Before you can use an API, you have to figure out how to get credentials to access the API. This can often be one of the trickiest steps when getting started with a new API. We learned last week that there are predominantly two different conceptual models when authenticating with an API. ... OAuth is often used to access data on behalf of an end-user, but there are multiple versions of OAuth, there are inconsistencies in how it is implemented, and getting the user interface right for the end-user can be tricky. Oftentimes the confusion that arises with authentication comes from a gap between how the API team thinks about the use cases for the API and how the customer thinks about the use cases for the API. When there’s a mismatch, the needed authentication mechanism might not be available. … ## Sloppy Implementations of REST Principles Finally, developers can struggle to adopt a new API because the API doesn’t act according to their expectations. As we saw last week, REST is a standard that sits on top of HTTP. That means there are expected norms that should be followed when you create a REST API. These norms apply to how we define our endpoints. An endpoint should grant access to a resource. They apply when we define our methods. A PUT should replace a resource. A PATCH should partially update a resource. There are norms for how requests and responses should be structured. But many APIs do a sloppy job of following these norms. Endpoints map to actions instead of resources. PUTs act like PATCHes. Responses have incorrect status codes or status descriptors, are missing necessary headers, or include empty bodies when it’s more appropriate to return a resource.