APIful Blog We're obsessed with Web APIs


Web API Documentation Can Be Confusing to Read

Jinqiu Yang

Developers can be misled by Web API documentation if it is rather confusing. In this blogpost, I will summarize some confusing cases of Web API documentation which I came across in my research recently.

Web API documentation is the first source of information when a user wants to understand how to use a Web API. As one may expect, these Web API documentation should be accurate and complete. Nevertheless, all too often, we see many issues in these official Web API documentation. Errors and ambiguities in Web API documentation can confuse users on the proper usage of these APIs; consequently, users need to spend extra time and efforts to figure out the correct way to use a Web API. In many cases, users even need to spend a significant amount of time to diagnose failures from such incorrect Web API usages that are caused by incorrect or misleading API documentation.

Errors

It is common that human-written documentation contains errors such as typos. However, if typos occur in the examples on how to use endpoints, these typos can introduce troubles for API users. For example, in “I Am Real” API documentation, the example to describe the endpoint – “GET validation results” contains a typo in the endpoint URL:
GET https://api.iamreal.me/ap/v2/sms/check/{userId}?appId={appId}&appSecret={appSecret}&phoneNumber={phoneNumber}&validationCode={validationCode}
The URL listed in the above example should be “…/api/v2/sms…” instead of “…/ap/v2/sms…”. Directly copying this URL into the code would cause some troubles for users when they realize that the example code does not work as expected.

Another example is from ClickMeter API, in which all the endpoints about aggregated reports contain typos. For example, “GET /datatpoints/{id}/aggregated/list” is the documentation is incorrect and should be “GET /datapoints/{id}/aggregated/list” instead.

For the above-mentioned documentation errors, users may determine the correct API usage by carefully cross compare the problematic endpoints with other endpoint descriptions from the same Web API. For example, another endpoint URL–“POST a token for analysis” is correctly listed as POST https://api.iamreal.me/api/v2/users/{userId}, in which “…/api/v2/…” is correctly written.

Ambiguities

Ambiguities in documentation come from multiple aspects. Ambiguities make readers confused when studying documentation to understand correct usages of a Web API.

First, unclear descriptions that fail to distinguish between base URL and endpoint URLs can confuse API users. For example, the documentation of CFPB Open Tech describes https://api.consumerfinance.gov/data/hmda at the very beginning, then the documentation lists several endpoints in parallel. Guided by the structure of the documentation, users could consider “https://api.consumerfinance.gov/data/hmda” as base URL. Since endpoints are listed as “/data/{dataset-name}”, it is natural that readers would consisder that the full URL is https://api.consumerfinance.gov/data/hmda/data/{dataset-name} by aggregating base URL and endpoint URL. However, the correct full URL is https://api.consumerfinance.gov/data/{dataset-name}.

Second, unclear or inconsistent descriptions of endpoints, particularly the path parameters, make it hard for users to understand the true intentions of the API provider. This is caused by the fact that API providers provide a summary of endpoints, which are often presented in the format of endpoints. An example of such a case is the documentation of City Context Web API. The summary is given as
https://api.citycontext.com/v2/<location>/<dataset>?user_key=<your user key>.
This can be interpreted as having two path parameters in one endpoint: location and dataset. But, in fact, this Web API constitutes of two endpoints: 1) /@{lat}, {lon}/<dataset>; and 2) /postcodes/{postcodes}/<dataset>. The two actual endpoints are not accurately summarized as /<location>/<dataset>. Summarizing the endpoints as /<location>/<dataset> in the beginning of the documentation can be rather misleading for the actual endpoint /postcodes/{postcodes}/<dataset>.

Challenges in Understanding Web API Documentations in Natural Language

In summary, Web API documentation can be rather confusing for human beings to understand when there are errors and ambiguities in these documentation. It motivates us to create tools to help writers to create and validate API documentation in order to avoid these errors. Has the documentation of an API let you down? What is your favorite API documentation?

Share via a Tweet or follow us for everything APIs!