loading
Papers Papers/2022 Papers Papers/2022

Research.Publish.Connect.

Paper

Authors: Gloria Bondel ; Arif Cerit and Florian Matthes

Affiliation: Faculty of Informatics, Technical University of Munich, Boltzmannstrasse 3, Garching, Germany

Keyword(s): API Documentation, Web APIs, Challenges, Best Practices.

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 partici pants. As a result, we validate the analyzed eight best practices candidates to be best practices for public Web API documentation. (More)

CC BY-NC-ND 4.0

Sign In Guest: Register as new SciTePress user now for free.

Sign In SciTePress user: please login.

PDF ImageMy Papers

You are not signed in, therefore limits apply to your IP address 174.129.93.231

In the current month:
Recent papers: 100 available of 100 total
2+ years older papers: 200 available of 200 total

Paper citation in several formats:
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 2: ICEIS; ISBN 978-989-758-569-2; ISSN 2184-4992, SciTePress, pages 268-279. DOI: 10.5220/0011089700003179

@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 2: ICEIS},
year={2022},
pages={268-279},
publisher={SciTePress},
organization={INSTICC},
doi={10.5220/0011089700003179},
isbn={978-989-758-569-2},
issn={2184-4992},
}

TY - CONF

JO - Proceedings of the 24th International Conference on Enterprise Information Systems - Volume 2: 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
IS - 2184-4992
AU - Bondel, G.
AU - Cerit, A.
AU - Matthes, F.
PY - 2022
SP - 268
EP - 279
DO - 10.5220/0011089700003179
PB - SciTePress