Inappropriate Usage Examples in Web API Documentations

Abstract

Application Programming Interfaces (APIs) are common in software development to reuse other products. Although the documentation allows API consumers to learn about API usages, it can be unreliable. Here, we investigate the characteristics of inappropriate usage examples in web API documentation by extracting and comparing OpenAPI Specifications from usage example-response pairs. About 65.5% of the endpoints have some form of inappropriate usage examples. Furthermore, mismatches are classified into four categories: undocumented keys pattern, dynamic keys pattern, unreturned keys pattern, and type mismatched pattern. Our results suggest that the number of keys in the response is correlated with the number of mismatches. These findings should assist both API providers and consumers who deal with unreliable documentation in web APIs.