Web API文档中的不当用法示例

2019 IEEE International Conference on Software Maintenance and Evolution (ICSME) Pub Date : 2019-09-01 DOI:10.1109/ICSME.2019.00052

Masaki Hosono, Susumu Tokumoto, S. Monpratarnchai, H. Washizaki, Kiyoshi Honda, Hiromasa Nagumo, Hisanobu Sonoda, Y. Fukazawa, Kazuki Munakata, Takao Nakagawa, Yusuke Nemoto

{"title":"Web API文档中的不当用法示例","authors":"Masaki Hosono, Susumu Tokumoto, S. Monpratarnchai, H. Washizaki, Kiyoshi Honda, Hiromasa Nagumo, Hisanobu Sonoda, Y. Fukazawa, Kazuki Munakata, Takao Nakagawa, Yusuke Nemoto","doi":"10.1109/ICSME.2019.00052","DOIUrl":null,"url":null,"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.","PeriodicalId":106748,"journal":{"name":"2019 IEEE International Conference on Software Maintenance and Evolution (ICSME)","volume":null,"pages":null},"PeriodicalIF":0.0000,"publicationDate":"2019-09-01","publicationTypes":"Journal Article","fieldsOfStudy":null,"isOpenAccess":false,"openAccessPdf":"","citationCount":"1","resultStr":"{\"title\":\"Inappropriate Usage Examples in Web API Documentations\",\"authors\":\"Masaki Hosono, Susumu Tokumoto, S. Monpratarnchai, H. Washizaki, Kiyoshi Honda, Hiromasa Nagumo, Hisanobu Sonoda, Y. Fukazawa, Kazuki Munakata, Takao Nakagawa, Yusuke Nemoto\",\"doi\":\"10.1109/ICSME.2019.00052\",\"DOIUrl\":null,\"url\":null,\"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.\",\"PeriodicalId\":106748,\"journal\":{\"name\":\"2019 IEEE International Conference on Software Maintenance and Evolution (ICSME)\",\"volume\":null,\"pages\":null},\"PeriodicalIF\":0.0000,\"publicationDate\":\"2019-09-01\",\"publicationTypes\":\"Journal Article\",\"fieldsOfStudy\":null,\"isOpenAccess\":false,\"openAccessPdf\":\"\",\"citationCount\":\"1\",\"resultStr\":null,\"platform\":\"Semanticscholar\",\"paperid\":null,\"PeriodicalName\":\"2019 IEEE International Conference on Software Maintenance and Evolution (ICSME)\",\"FirstCategoryId\":\"1085\",\"ListUrlMain\":\"https://doi.org/10.1109/ICSME.2019.00052\",\"RegionNum\":0,\"RegionCategory\":null,\"ArticlePicture\":[],\"TitleCN\":null,\"AbstractTextCN\":null,\"PMCID\":null,\"EPubDate\":\"\",\"PubModel\":\"\",\"JCR\":\"\",\"JCRName\":\"\",\"Score\":null,\"Total\":0}","platform":"Semanticscholar","paperid":null,"PeriodicalName":"2019 IEEE International Conference on Software Maintenance and Evolution (ICSME)","FirstCategoryId":"1085","ListUrlMain":"https://doi.org/10.1109/ICSME.2019.00052","RegionNum":0,"RegionCategory":null,"ArticlePicture":[],"TitleCN":null,"AbstractTextCN":null,"PMCID":null,"EPubDate":"","PubModel":"","JCR":"","JCRName":"","Score":null,"Total":0}

引用次数: 1

摘要

应用程序编程接口(api)在软件开发中用于重用其他产品是很常见的。尽管文档允许API使用者了解API的用法，但它可能不可靠。在这里，我们通过从使用示例-响应对中提取和比较OpenAPI规范来研究web API文档中不适当使用示例的特征。大约65.5%的端点存在某种形式的不当用法示例。此外，将不匹配分为四类:未记录的键模式、动态键模式、未返回的键模式和类型不匹配模式。我们的结果表明，响应中的键的数量与不匹配的数量相关。这些发现应该有助于处理web API中不可靠文档的API提供者和消费者。

本文章由计算机程序翻译，如有差异，请以英文原文为准。

查看原文本刊更多论文

Inappropriate Usage Examples in Web API Documentations

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.

求助全文

通过发布文献求助，成功后即可免费获取论文全文。去求助

来源期刊

2019 IEEE International Conference on Software Maintenance and Evolution (ICSME)

自引率

0.00%

发文量