- Research Article
- 10.5753/jserd.2024.4130
Colloquy: Evidence-Based Method for Supporting the Design of Conversational APIs
- Feb 18, 2025
- Journal of Software Engineering Research and Development
- João Antônio D M Bastos + 2 more +2
Application Programming Interfaces (APIs) are everyday tools for every software professional. When creating an API, a designer typically abstracts the tasks the API intends to perform. The API user, on the other hand, should use the API to perform specific-propose tasks. During the development of an API, the designer needs to write dialogues with which the user will interact with the API, performing a conversation between them. In this way, an API capable of offering effective dialogues to its users is called a conversational API. A conversational API is the one that is capable of communicating to its users its form of use and its internal logic of operation, making it clear the design decisions when abstracting concepts and tasks. In this paper, we present Colloquy, an evidence-based method to support the design of conversational APIs. Colloquy was conceived based on the lessons learned from an action research we conducted to identify effective strategies for designing conversational APIs. For six months, we followed the redesign of an existing API developed at an R&D laboratory of a large IT company. In this paper, we also present the first empirical evaluation of Colloquy. We conducted a case study in which the method was employed to design an API for refactoring source code in the Java programming language. Among other benefits, we found that Colloquy was effective in developing empathy with users and modeling conversations with them. Besides, Colloquy contributed to identifying new requirements and created models as API documentation.
Read more