Inappropriate Usage Examples in Web API Documentations

Masaki Hosono, Susumu Tokumoto, Supasit Monpratarnchai, Hironori Washizaki, Kiyoshi Honda, Hiromasa Nagumo, Hisanobu Sonoda, Yoshiaki Fukazawa, Kazuki Munakata, Takao Nakagawa, Yusuke Nemoto

Research output: Chapter in Book/Report/Conference proceedingConference contribution

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.

Original languageEnglish
Title of host publicationProceedings - 2019 IEEE International Conference on Software Maintenance and Evolution, ICSME 2019
PublisherInstitute of Electrical and Electronics Engineers Inc.
Pages343-347
Number of pages5
ISBN (Electronic)9781728130941
DOIs
Publication statusPublished - 2019 Sep
Event2019 IEEE International Conference on Software Maintenance and Evolution, ICSME 2019 - Cleveland, United States
Duration: 2019 Sep 302019 Oct 4

Publication series

NameProceedings - 2019 IEEE International Conference on Software Maintenance and Evolution, ICSME 2019

Conference

Conference2019 IEEE International Conference on Software Maintenance and Evolution, ICSME 2019
CountryUnited States
CityCleveland
Period19/9/3019/10/4

Keywords

  • Documentation
  • Learnability
  • Reliability
  • REST
  • Usability
  • Usage Example
  • Web API

ASJC Scopus subject areas

  • Software
  • Safety, Risk, Reliability and Quality

Fingerprint Dive into the research topics of 'Inappropriate Usage Examples in Web API Documentations'. Together they form a unique fingerprint.

  • Cite this

    Hosono, M., Tokumoto, S., Monpratarnchai, S., Washizaki, H., Honda, K., Nagumo, H., Sonoda, H., Fukazawa, Y., Munakata, K., Nakagawa, T., & Nemoto, Y. (2019). Inappropriate Usage Examples in Web API Documentations. In Proceedings - 2019 IEEE International Conference on Software Maintenance and Evolution, ICSME 2019 (pp. 343-347). [8919166] (Proceedings - 2019 IEEE International Conference on Software Maintenance and Evolution, ICSME 2019). Institute of Electrical and Electronics Engineers Inc.. https://doi.org/10.1109/ICSME.2019.00052