Inappropriate Usage Examples in Web API Documentations

被引：1

作者：

Hosono, Masaki ^{[1
]}

Washizaki, Hironori ^{[1
]}

Honda, Kiyoshi ^{[1
]}

Nagumo, Hiromasa ^{[1
]}

Sonoda, Hisanobu ^{[1
]}

Fukazawa, Yoshiaki ^{[1
]}

Munakata, Kazuki ^{[2
]}

Nakagawa, Takao ^{[2
]}

Nemoto, Yusuke ^{[2
]}

Tokumoto, Susumu ^{[2
]}

Monpratarnchai, Supasit ^{[2
]}

机构：

[1] Waseda Univ, Tokyo, Japan

[2] Fujitsu Labs Ltd, Kawasaki, Kanagawa, Japan

来源：

2019 IEEE INTERNATIONAL CONFERENCE ON SOFTWARE MAINTENANCE AND EVOLUTION (ICSME 2019) | 2019年

关键词：

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

D O I：

10.1109/ICSME.2019.00052

中图分类号：

TP31 [计算机软件];

学科分类号：

081202 ; 0835 ;

摘要：

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.

引用

页码：343 / 347

页数：5

共 13 条

[1] Example-Driven Web API Specification Discovery [J].

Ed-douibi, Hamza ;

Canovas Izquierdo, Javier Luis ;

Cabot, Jordi .

MODELLING FOUNDATIONS AND APPLICATIONS, ECMFA 2017, 2017, 10376 :267-284

[2]

Jun Li, 2013, 2013 IEEE 20th International Conference on Web Services (ICWS), P300, DOI 10.1109/ICWS.2013.48

[3] Patterns of Knowledge in API Reference Documentation [J].

Maalej, Walid ;

Robillard, Martin P. .

IEEE TRANSACTIONS ON SOFTWARE ENGINEERING, 2013, 39 (09) :1264-1282

[4] Building more usable APIs [J].

McLellan, SG ;

Roesler, AW ;

Tempest, JT ;

Spinuzzi, CI .

IEEE SOFTWARE, 1998, 15 (03) :78-+

[5] QoS issues in Web services [J].

Menascé, DA .

IEEE INTERNET COMPUTING, 2002, 6 (06) :72-75

[6] Improving API Usability [J].

Myers, Brad A. ;

Stylos, Jeffrey .

COMMUNICATIONS OF THE ACM, 2016, 59 (06) :62-69

[7] What Makes APIs Hard to Learn? Answers from Developers [J].

Robillard, Martin P. .

IEEE SOFTWARE, 2009, 26 (06) :27-34

[8]

Shi L, 2011, LECT NOTES COMPUT SC, V6603, P416, DOI 10.1007/978-3-642-19811-3_29

[9]

Sohan SM, 2017, S VIS LANG HUM CEN C, P53, DOI 10.1109/VLHCC.2017.8103450

[10] Closing the Gap between Unit Test Code and Documentation [J].

Stoecker, Karsten ;

Washizaki, Hironori ;

Fukazawa, Yoshiaki .

10TH IEEE INTERNATIONAL CONFERENCE ON SOFTWARE TESTING, VERIFICATION AND VALIDATION WORKSHOPS - ICSTW 2017, 2017, :304-308

← 1 2 →