TY - GEN
T1 - Inappropriate Usage Examples in Web API Documentations
AU - Hosono, Masaki
AU - Tokumoto, Susumu
AU - Monpratarnchai, Supasit
AU - Washizaki, Hironori
AU - Honda, Kiyoshi
AU - Nagumo, Hiromasa
AU - Sonoda, Hisanobu
AU - Fukazawa, Yoshiaki
AU - Munakata, Kazuki
AU - Nakagawa, Takao
AU - Nemoto, Yusuke
PY - 2019/9
Y1 - 2019/9
N2 - 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.
AB - 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.
KW - Documentation
KW - Learnability
KW - Reliability
KW - REST
KW - Usability
KW - Usage Example
KW - Web API
UR - http://www.scopus.com/inward/record.url?scp=85077210971&partnerID=8YFLogxK
UR - http://www.scopus.com/inward/citedby.url?scp=85077210971&partnerID=8YFLogxK
U2 - 10.1109/ICSME.2019.00052
DO - 10.1109/ICSME.2019.00052
M3 - Conference contribution
AN - SCOPUS:85077210971
T3 - Proceedings - 2019 IEEE International Conference on Software Maintenance and Evolution, ICSME 2019
SP - 343
EP - 347
BT - Proceedings - 2019 IEEE International Conference on Software Maintenance and Evolution, ICSME 2019
PB - Institute of Electrical and Electronics Engineers Inc.
T2 - 2019 IEEE International Conference on Software Maintenance and Evolution, ICSME 2019
Y2 - 30 September 2019 through 4 October 2019
ER -