Colloquy: Evidence-Based Method for Supporting the Design of Conversational APIs
DOI:
https://doi.org/10.5753/jserd.2024.4130Keywords:
API, Conversation, Action Research, Case Study, Semiotic EngineeringAbstract
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.
Downloads
References
Afonso, L. M. (2015a). Communicative dimensions of application programming interfaces (APIs). PhD thesis, Programa de Pós-Graduaçao em In-formática of the Departamento de Informática ….
Afonso, L. M. (2015b). Communicative dimensions of application programming interfaces (APIs). PhD Thesis, Programa de Pós-Graduaçao em Informática of the Departamento de Informática ….
Bastos, J., Mello, R., and Garcia, A. (2023). On the support for designing a conversational software api: An action research study: An action research study. In Proceedings of the XXXVII Brazilian Symposium on Software Engineering, pages 57–66.
Bastos, J. A., Afonso, L. M., and de Souza, C. S. (2017). Metacommunication between programmers through an application programming interface: A semiotic analysis of date and time APIs. In 2017 IEEE Symposium on Visual Languages and Human-Centric Computing (VL/HCC), pages 213–221. ISSN: 1943-6106.
Bastos, J. A. D., de Mello, R. M., and Garcia, A. (2020a). Colloquy: A method for conversational api design. In Proceedings of the XXXIV Brazilian Symposium on Software Engineering, pages 514–519.
Bastos, J. A. D., de Mello, R. M., and Garcia, A. F. (2020b). A conceptual framework for conversational apis. In Proceedings of the XXXIV Brazilian Symposium on Software Engineering, pages 509–513.
Carroll, J. M. (2000). Making use: scenario-based design of human-computer interactions. MIT press.
Cooper, A. (2004). The inmates are running the asylum:[Why high-tech products drive us crazy and how to restore the sanity], volume 2. Sams Indianapolis.
Costa Neto, M. A. (2013). Uma linguagem de modelagem da interação para auxiliar a comunicação designer-usuário.
de Paula, M. G. and Barbosa, S. D. J. (2003). Designing and Evaluating Interaction as Conversation: A Modeling Language Based on Semiotic Engineering. In Jorge, J. A., Jardim Nunes, N., and Falcão e Cunha, J., editors, Interactive Systems. Design, Specification, and Verification, Lecture Notes in Computer Science, pages 16–33, Berlin, Heidelberg. Springer.
De Souza, C. S. (2005). The semiotic engineering of human-computer interaction. MIT press.
Fowler, M. (2004). Refatoração: Aperfeiçoamento e Projeto. Bookman. Google-Books-ID: xV2_wAEACAAJ.
Grice, H. P. (1975). Logic and Conversation. In Speech acts, pages 41–58. Brill.
Henning, M. (2007). API Design Matters. Queue, 5(4):24–36.
Ichinco, M., Hnin, W. Y., and Kelleher, C. L. (2017). Suggesting API Usage to Novice Programmers with the Example Guru. In Proceedings of the 2017 CHI Conference on Human Factors in Computing Systems, CHI ’17, pages 1105–1117, Denver, Colorado, USA. Association for Computing Machinery.
Initiative, O. A. (2020). OpenAPI Specification.
Lamothe, M. and Shang, W. (2020). When APIs are Intentionally Bypassed: An Exploratory Study of API Workarounds. page 13.
McLellan, S., Roesler, A., Tempest, J., and Spinuzzi, C. (1998). Building more usable APIs. IEEE Software, 15(3):78–86. Conference Name: IEEE Software.
Mindermann, K. (2016). Are easily usable security libraries possible and how should experts work together to create them? In Proceedings of the 9th International Workshop on Cooperative and Human Aspects of Software Engineering, CHASE ’16, pages 62–63, Austin, Texas. Association for Computing Machinery.
Mosqueira-Rey, E., Alonso-Ríos, D., Moret-Bonillo, V., Fernández-Varela, I., and Álvarez Estévez, D. (2018). A systematic approach to API usability: Taxonomy-derived criteria and a case study. Information and Software Technology, 97:46–63.
Murphy, L., Kery, M. B., Alliyu, O., Macvean, A., and Myers, B. A. (2018). API Designers in the Field: Design Practices and Challenges for Creating Usable APIs. In 2018 IEEE Symposium on Visual Languages and Human-Centric Computing (VL/HCC), pages 249–258. ISSN: 1943-6106.
Myers, B. A. and Stylos, J. (2016). Improving API usability. Communications of the ACM, 59(6):62–69. Publisher: ACM New York, NY, USA.
Nguyen, D. C., Wermke, D., Acar, Y., Backes, M., Weir, C., and Fahl, S. (2017). A Stitch in Time: Supporting Android Developers in WritingSecure Code. In Proceedings of the 2017 ACM SIGSAC Conference on Computer and Communications Security, CCS ’17, pages 1065–1077, Dallas, Texas, USA. Association for Computing Machinery.
Nielebock, S., Heumüller, R., Krüger, J., and Ortmeier, F. (2020). Cooperative API Misuse Detection Using Correction Rules. page 4.
Nielsen, J. (1994). Usability Engineering. Morgan Kaufmann. Google-Books-ID: 95As2OF67f0C.
Oliveira, J., Gheyi, R., Mongiovi, M., Soares, G., Ribeiro, M., and Garcia, A. (2019). Revisiting the refactoring mechanics. Information and Software Technology, 110:136–138.
OMG (2016). About the Unified Modeling Language Specification Version 2.5.1.
Pontes, F., Gheyi, R., Souto, S., Garcia, A., and Ribeiro, M. (2019). Java Reflection API: Revealing the Dark Side of the Mirror. In Proceedings of the 2019 27th ACM Joint Meeting on European Software Engineering Conference and Symposium on the Foundations of Software Engineering, ESEC/FSE 2019, pages 636–646, New York, NY, USA. Association for Computing Machinery. event-place: Tallinn, Estonia.
Rosson, M. B. and Carroll, J. M. (2002). Usability Engineering: Scenario-Based Development of Human-Computer Interaction. Morgan Kaufmann. Google-Books-ID: sRPg0IYhYFYC.
Sangiorgi, U. B. and Barbosa, S. D. (2009). MoLIC designer: towards computational support to hci design with MoLIC. In Proceedings of the 1st ACM SIGCHI symposium on Engineering interactive computing systems, EICS ’09, pages 303–308, Pittsburgh, PA, USA. Association for Computing Machinery.
Souders, S. (2008). High-performance web sites. Communications of the ACM, 51(12):36–41.
Souza, C. S. d., Cerqueira, R. F. d. G., Afonso, L. M., Brandão, R. R. d. M., and Ferreira, J. S. J. (2016). Software Developers as Users : Semiotic Investigations in Human-Centered Software Development. Springer International Publishing.
Stylos, J. and Clarke, S. (2007). Usability Implications of Requiring Parameters in Objects’ Constructors. In Proceedings of the 29th international conference on Software Engineering, ICSE ’07, pages 529–539, USA. IEEE Computer Society.
Stylos, J. and Myers, B. A. (2008). The implications of method placement on API learnability. In Proceedings of the 16th ACM SIGSOFT International Symposium on Foundations of software engineering, SIGSOFT ’08/FSE-16, pages 105–112, Atlanta, Georgia. Association for Computing Machinery.
Thiollent, M. (1996). Metodologia da pesquisa–ação (7ª edição). São Paulo-SP.
Watson, R. (2014). Applying the Cognitive Dimensions of API Usability to Improve API Documentation Planning. In Proceedings of the 32nd ACM International Conference on The Design of Communication CD-ROM, SIGDOC ’14, pages 1–2, Colorado Springs, CO, USA. Association for Computing Machinery.
Weinberg, G. M. (1971). The Psychology of Computer Programming, volume 29. Van Nostrand Reinhold New York.
Wohlin, C., Runeson, P., Höst, M., Ohlsson, M. C., Regnell, B., and Wesslén, A. (2012). Experimentation in Software Engineering. Springer-Verlag, Berlin Heidelberg.
Yessenov, K., Kuraj, I., and Solar-Lezama, A. (2017). DemoMatch: API discovery from demonstrations. ACM SIGPLAN Notices, 52(6):64–78.
Zhang, J., Jiang, H., Ren, Z., Zhang, T., and Huang, Z. (2019). Enriching API Documentation with Code Samples and Usage Scenarios from Crowd Knowledge. IEEE Transactions on Software Engineering, pages 1–1. Conference Name: IEEE Transactions on Software Engineering.
Downloads
Published
How to Cite
Issue
Section
License
Copyright (c) 2025 João Antonio D. M. Bastos, Rafael Maiani de Mello, Alessandro Fabricio Garcia
This work is licensed under a Creative Commons Attribution 4.0 International License.
