An Empirical Study on the Reliability of the Web API Document

Masaki Hosono, Hironori Washizaki, Yoshiaki Fukazawa, Kiyoshi Honda

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

Abstract

The importance of APIs in software development, especially web APIs, has increased Developers read documentation, which is available on the internet, and use the corresponding APIs in their products. However, documentation occasionally contains mistakes. Such mistakes can confuse developers or lead to defects that lower the quality of the product. In this paper, we investigate the reliability of web APIs by extracting and comparing OpenAPI specifications from both the documentations and the results of the API calls. Almost half of the documentations are somehow unreliable. Mismatches between documentation and the response can be categorized into four types: 1) Undocumented Keys, 2) Dynamic Keys, 3) Unreturned Keys, and 4) Type Mismatched. This study will help developers design more reliable products.

Original languageEnglish
Title of host publicationProceedings - 25th Asia-Pacific Software Engineering Conference, APSEC 2018
PublisherIEEE Computer Society
Pages715-716
Number of pages2
ISBN (Electronic)9781728119700
DOIs
Publication statusPublished - 2019 May 21
Event25th Asia-Pacific Software Engineering Conference, APSEC 2018 - Nara, Japan
Duration: 2018 Dec 42018 Dec 7

Publication series

NameProceedings - Asia-Pacific Software Engineering Conference, APSEC
Volume2018-December
ISSN (Print)1530-1362

Conference

Conference25th Asia-Pacific Software Engineering Conference, APSEC 2018
CountryJapan
CityNara
Period18/12/418/12/7

Fingerprint

Application programming interfaces (API)
Software engineering
Internet
Specifications
Defects

Keywords

  • API documentation
  • documentation evolution
  • microservices
  • REST API
  • Web API

ASJC Scopus subject areas

  • Software

Cite this

Hosono, M., Washizaki, H., Fukazawa, Y., & Honda, K. (2019). An Empirical Study on the Reliability of the Web API Document. In Proceedings - 25th Asia-Pacific Software Engineering Conference, APSEC 2018 (pp. 715-716). [8719480] (Proceedings - Asia-Pacific Software Engineering Conference, APSEC; Vol. 2018-December). IEEE Computer Society. https://doi.org/10.1109/APSEC.2018.00103

An Empirical Study on the Reliability of the Web API Document. / Hosono, Masaki; Washizaki, Hironori; Fukazawa, Yoshiaki; Honda, Kiyoshi.

Proceedings - 25th Asia-Pacific Software Engineering Conference, APSEC 2018. IEEE Computer Society, 2019. p. 715-716 8719480 (Proceedings - Asia-Pacific Software Engineering Conference, APSEC; Vol. 2018-December).

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

Hosono, M, Washizaki, H, Fukazawa, Y & Honda, K 2019, An Empirical Study on the Reliability of the Web API Document. in Proceedings - 25th Asia-Pacific Software Engineering Conference, APSEC 2018., 8719480, Proceedings - Asia-Pacific Software Engineering Conference, APSEC, vol. 2018-December, IEEE Computer Society, pp. 715-716, 25th Asia-Pacific Software Engineering Conference, APSEC 2018, Nara, Japan, 18/12/4. https://doi.org/10.1109/APSEC.2018.00103
Hosono M, Washizaki H, Fukazawa Y, Honda K. An Empirical Study on the Reliability of the Web API Document. In Proceedings - 25th Asia-Pacific Software Engineering Conference, APSEC 2018. IEEE Computer Society. 2019. p. 715-716. 8719480. (Proceedings - Asia-Pacific Software Engineering Conference, APSEC). https://doi.org/10.1109/APSEC.2018.00103
Hosono, Masaki ; Washizaki, Hironori ; Fukazawa, Yoshiaki ; Honda, Kiyoshi. / An Empirical Study on the Reliability of the Web API Document. Proceedings - 25th Asia-Pacific Software Engineering Conference, APSEC 2018. IEEE Computer Society, 2019. pp. 715-716 (Proceedings - Asia-Pacific Software Engineering Conference, APSEC).
@inproceedings{41d25e0a5c034dbc88322954d97c0937,
title = "An Empirical Study on the Reliability of the Web API Document",
abstract = "The importance of APIs in software development, especially web APIs, has increased Developers read documentation, which is available on the internet, and use the corresponding APIs in their products. However, documentation occasionally contains mistakes. Such mistakes can confuse developers or lead to defects that lower the quality of the product. In this paper, we investigate the reliability of web APIs by extracting and comparing OpenAPI specifications from both the documentations and the results of the API calls. Almost half of the documentations are somehow unreliable. Mismatches between documentation and the response can be categorized into four types: 1) Undocumented Keys, 2) Dynamic Keys, 3) Unreturned Keys, and 4) Type Mismatched. This study will help developers design more reliable products.",
keywords = "API documentation, documentation evolution, microservices, REST API, Web API",
author = "Masaki Hosono and Hironori Washizaki and Yoshiaki Fukazawa and Kiyoshi Honda",
year = "2019",
month = "5",
day = "21",
doi = "10.1109/APSEC.2018.00103",
language = "English",
series = "Proceedings - Asia-Pacific Software Engineering Conference, APSEC",
publisher = "IEEE Computer Society",
pages = "715--716",
booktitle = "Proceedings - 25th Asia-Pacific Software Engineering Conference, APSEC 2018",

}

TY - GEN

T1 - An Empirical Study on the Reliability of the Web API Document

AU - Hosono, Masaki

AU - Washizaki, Hironori

AU - Fukazawa, Yoshiaki

AU - Honda, Kiyoshi

PY - 2019/5/21

Y1 - 2019/5/21

N2 - The importance of APIs in software development, especially web APIs, has increased Developers read documentation, which is available on the internet, and use the corresponding APIs in their products. However, documentation occasionally contains mistakes. Such mistakes can confuse developers or lead to defects that lower the quality of the product. In this paper, we investigate the reliability of web APIs by extracting and comparing OpenAPI specifications from both the documentations and the results of the API calls. Almost half of the documentations are somehow unreliable. Mismatches between documentation and the response can be categorized into four types: 1) Undocumented Keys, 2) Dynamic Keys, 3) Unreturned Keys, and 4) Type Mismatched. This study will help developers design more reliable products.

AB - The importance of APIs in software development, especially web APIs, has increased Developers read documentation, which is available on the internet, and use the corresponding APIs in their products. However, documentation occasionally contains mistakes. Such mistakes can confuse developers or lead to defects that lower the quality of the product. In this paper, we investigate the reliability of web APIs by extracting and comparing OpenAPI specifications from both the documentations and the results of the API calls. Almost half of the documentations are somehow unreliable. Mismatches between documentation and the response can be categorized into four types: 1) Undocumented Keys, 2) Dynamic Keys, 3) Unreturned Keys, and 4) Type Mismatched. This study will help developers design more reliable products.

KW - API documentation

KW - documentation evolution

KW - microservices

KW - REST API

KW - Web API

UR - http://www.scopus.com/inward/record.url?scp=85066784099&partnerID=8YFLogxK

UR - http://www.scopus.com/inward/citedby.url?scp=85066784099&partnerID=8YFLogxK

U2 - 10.1109/APSEC.2018.00103

DO - 10.1109/APSEC.2018.00103

M3 - Conference contribution

AN - SCOPUS:85066784099

T3 - Proceedings - Asia-Pacific Software Engineering Conference, APSEC

SP - 715

EP - 716

BT - Proceedings - 25th Asia-Pacific Software Engineering Conference, APSEC 2018

PB - IEEE Computer Society

ER -