Challenges of API Documentation from a Provider Perspective and Best Practices for Examples in Public Web API Documentation

Gloria Bondel, Arif Cerit, Florian Matthes

2022

Abstract

Developers frequently have to learn new Web APIs provided by other teams or organizations. Documentation, especially code examples, supports learning and influences the consumers’ perception of an API. Nevertheless, documentation repeatedly fails to address consumers’ information needs. Therefore, we identify four major challenges of creating and maintaining public Web API documentation from a provider perspective which are unknown customer needs, the difficulty of balancing the coverage of varying information needs and keeping documentation concise, the high effort of creating and maintaining documentation, and missing internal guidance and governance for creating API documentation. In addition, we derive 46 best practices candidates for code examples as part of Web API documentation from literature and 13 expert interviews. Moreover, we evaluate a subset of eight of these candidates in the context of the Web API documentation for a public GraphQL API in a case study with 12 participants. As a result, we validate the analyzed eight best practices candidates to be best practices for public Web API documentation.

Paper Citation

in Harvard Style

Bondel G., Cerit A. and Matthes F. (2022). Challenges of API Documentation from a Provider Perspective and Best Practices for Examples in Public Web API Documentation. In Proceedings of the 24th International Conference on Enterprise Information Systems - Volume 1: ICEIS, ISBN 978-989-758-569-2, pages 268-279. DOI: 10.5220/0011089700003179

in Bibtex Style

@conference{iceis22,
author={Gloria Bondel and Arif Cerit and Florian Matthes},
title={Challenges of API Documentation from a Provider Perspective and Best Practices for Examples in Public Web API Documentation},
booktitle={Proceedings of the 24th International Conference on Enterprise Information Systems - Volume 1: ICEIS,},
year={2022},
pages={268-279},
publisher={SciTePress},
organization={INSTICC},
doi={10.5220/0011089700003179},
isbn={978-989-758-569-2},
}

in EndNote Style

TY - CONF

JO - Proceedings of the 24th International Conference on Enterprise Information Systems - Volume 1: ICEIS,
TI - Challenges of API Documentation from a Provider Perspective and Best Practices for Examples in Public Web API Documentation
SN - 978-989-758-569-2
AU - Bondel G.
AU - Cerit A.
AU - Matthes F.
PY - 2022
SP - 268
EP - 279
DO - 10.5220/0011089700003179