Colloquy

Abstract

APIs (application programming interfaces) play a key role in software development. Virtually, all programmers are potential users of third-party APIs. From the perspective of the theory of Semiotic Engineering, we may characterize an API as an artifact mediating the communication between two types of developers: the API designers and its users. During the construction of an API, the designers should establish proper dialogues with the users. These dialogues will enable the conversation of these actors at the interaction time. In this way, we define a conversational API as an API capable of offering effective dialogues to its users. In this paper, we introduce Colloquy, a method for supporting the design of conversational APIs. Colloquy results from the lessons learnt during an action research conducted for redesigning a real and complex API. The set of Colloquy resources allow API designers to go beyond conventional concerns with usability. We also report in this paper a case study in which Colloquy was used for redesigning a refactoring API. The study findings indicate the method helped the designer creating empathy with the API users, as well as better reflecting and depicting the requirements and the conversations that the API should attend to the different user profiles.