ABSTRACT
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, will 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. In this paper, we report the action research that 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. The action research required three complete cycles, exploring different techniques for supporting the API redesign. Based on this experience, we present in this paper a set of lessons learned and actionable solutions to support the design of conversational APIs.
- Luiz Marques Afonso. 2015. Communicative dimensions of application programming interfaces (APIs). Ph. D. Dissertation. Programa de Pós-Graduaçao em In-formática of the Departamento de Informática ….Google Scholar
- João A.D.M. Bastos, Luiz M. Afonso, and Clarisse S. de Souza. 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). 213–221. https://doi.org/10.1109/VLHCC.2017.8103470 ISSN: 1943-6106.Google ScholarCross Ref
- João Antonio DM Bastos, Rafael Maiani de Mello, and Alessandro Garcia. 2020. Colloquy: A Method for Conversational API Design. In Proceedings of the XXXIV Brazilian Symposium on Software Engineering. 514–519.Google ScholarDigital Library
- João Antonio DM Bastos, Rafael Maiani de Mello, and Alessandro Fabricio Garcia. 2020. A conceptual framework for conversational apis. In Proceedings of the XXXIV Brazilian Symposium on Software Engineering. 509–513.Google ScholarDigital Library
- John M Carroll. 2000. Making use: scenario-based design of human-computer interactions. MIT press.Google ScholarDigital Library
- Alan Cooper. 2004. The inmates are running the asylum:[Why high-tech products drive us crazy and how to restore the sanity]. Vol. 2. Sams Indianapolis.Google Scholar
- Maíra Greco de Paula and Simone Diniz Junqueira Barbosa. 2003. Designing and Evaluating Interaction as Conversation: A Modeling Language Based on Semiotic Engineering. In Interactive Systems. Design, Specification, and Verification(Lecture Notes in Computer Science), Joaquim A. Jorge, Nuno Jardim Nunes, and João Falcão e Cunha (Eds.). Springer, Berlin, Heidelberg, 16–33. https://doi.org/10.1007/978-3-540-39929-2_2Google ScholarCross Ref
- Clarisse Sieckenius De Souza. 2005. The semiotic engineering of human-computer interaction. MIT press.Google Scholar
- Herbert P Grice. 1975. Logic and Conversation. In Speech acts. Brill, 41–58.Google Scholar
- Michi Henning. 2007. API Design Matters. Queue 5, 4 (May 2007), 24–36. https://doi.org/10.1145/1255421.1255422Google ScholarDigital Library
- Michelle Ichinco, Wint Yee Hnin, and Caitlin L. Kelleher. 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). Association for Computing Machinery, Denver, Colorado, USA, 1105–1117. https://doi.org/10.1145/3025453.3025827Google ScholarDigital Library
- Open API Initiative. 2020. OpenAPI Specification. http://spec.openapis.org/oas/v3.0.3#fixed-fields-8Google Scholar
- Maxime Lamothe and Weiyi Shang. 2020. When APIs are Intentionally Bypassed: An Exploratory Study of API Workarounds. (2020), 13.Google Scholar
- S.G. McLellan, A.W. Roesler, J.T. Tempest, and C.I. Spinuzzi. 1998. Building more usable APIs. IEEE Software 15, 3 (May 1998), 78–86. https://doi.org/10.1109/52.676963 Conference Name: IEEE Software.Google ScholarDigital Library
- Kai Mindermann. 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). Association for Computing Machinery, Austin, Texas, 62–63. https://doi.org/10.1145/2897586.2897610Google ScholarDigital Library
- Eduardo Mosqueira-Rey, David Alonso-Ríos, Vicente Moret-Bonillo, Isaac Fernández-Varela, and Diego Álvarez Estévez. 2018. A systematic approach to API usability: Taxonomy-derived criteria and a case study. Information and Software Technology 97 (May 2018), 46–63. https://doi.org/10.1016/j.infsof.2017.12.010Google ScholarCross Ref
- Lauren Murphy, Mary Beth Kery, Oluwatosin Alliyu, Andrew Macvean, and Brad A. Myers. 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). 249–258. https://doi.org/10.1109/VLHCC.2018.8506523 ISSN: 1943-6106.Google ScholarCross Ref
- Brad A Myers and Jeffrey Stylos. 2016. Improving API usability. Commun. ACM 59, 6 (2016), 62–69. Publisher: ACM New York, NY, USA.Google ScholarDigital Library
- Macilon Araújo Costa Neto. [n. d.]. Uma linguagem de modelagem da interação para auxiliar a comunicação designer-usuário. ([n. d.]), 134.Google Scholar
- Sebastian Nielebock, Robert Heumüller, Jacob Krüger, and Frank Ortmeier. 2020. Cooperative API Misuse Detection Using Correction Rules. (2020), 4.Google Scholar
- Jakob Nielsen. 1994. Usability Engineering. Morgan Kaufmann. Google-Books-ID: 95As2OF67f0C.Google ScholarDigital Library
- Jonhnanthan Oliveira, Rohit Gheyi, Melina Mongiovi, Gustavo Soares, Márcio Ribeiro, and Alessandro Garcia. 2019. Revisiting the refactoring mechanics. Information and Software Technology 110 (June 2019), 136–138. https://doi.org/10.1016/j.infsof.2019.03.002Google ScholarDigital Library
- Felipe Pontes, Rohit Gheyi, Sabrina Souto, Alessandro Garcia, and Márcio Ribeiro. 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). Association for Computing Machinery, New York, NY, USA, 636–646. https://doi.org/10.1145/3338906.3338946 event-place: Tallinn, Estonia.Google ScholarDigital Library
- Mary Beth Rosson and John M. Carroll. 2002. Usability Engineering: Scenario-Based Development of Human-Computer Interaction. Morgan Kaufmann. Google-Books-ID: sRPg0IYhYFYC.Google ScholarCross Ref
- Ugo Braga Sangiorgi and Simone D.J. Barbosa. 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). Association for Computing Machinery, Pittsburgh, PA, USA, 303–308. https://doi.org/10.1145/1570433.1570489Google ScholarDigital Library
- Clarisse Sieckenius de Souza, Renato Fontoura de Gusmão Cerqueira, Luiz Marques Afonso, Rafael Rossi de Mello Brandão, and Juliana Soares Jansen Ferreira. 2016. Software Developers as Users : Semiotic Investigations in Human-Centered Software Development. Springer International Publishing. https://doi.org/10.1007/978-3-319-42831-4Google ScholarCross Ref
- UML Specification. [n. d.]. About the Unified Modeling Language Specification Version 2.5.1. https://www.omg.org/spec/UML/Google Scholar
- Jeffrey Stylos and Steven Clarke. 2007. Usability Implications of Requiring Parameters in Objects’ Constructors. In Proceedings of the 29th international conference on Software Engineering(ICSE ’07). IEEE Computer Society, USA, 529–539. https://doi.org/10.1109/ICSE.2007.92Google ScholarDigital Library
- Jeffrey Stylos and Brad A. Myers. 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). Association for Computing Machinery, Atlanta, Georgia, 105–112. https://doi.org/10.1145/1453101.1453117Google ScholarDigital Library
- Michel Thiollent. 1996. Metodologia da pesquisa–ação (7ª edição). São Paulo-SP.Google Scholar
- Robert Watson. 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). Association for Computing Machinery, Colorado Springs, CO, USA, 1–2. https://doi.org/10.1145/2666216.2666239Google ScholarDigital Library
- Gerald M Weinberg. 1971. The Psychology of Computer Programming. Vol. 29. Van Nostrand Reinhold New York.Google Scholar
- Kuat Yessenov, Ivan Kuraj, and Armando Solar-Lezama. 2017. DemoMatch: API discovery from demonstrations. ACM SIGPLAN Notices 52, 6 (June 2017), 64–78. https://doi.org/10.1145/3140587.3062386Google ScholarDigital Library
- Jingxuan Zhang, He Jiang, Zhilei Ren, Tao Zhang, and Zhiqiu Huang. 2019. Enriching API Documentation with Code Samples and Usage Scenarios from Crowd Knowledge. IEEE Transactions on Software Engineering (2019), 1–1. https://doi.org/10.1109/TSE.2019.2919304 Conference Name: IEEE Transactions on Software Engineering.Google ScholarCross Ref
Index Terms
- On the Support for Designing a Conversational Software API: An Action Research Study: An Action Research Study
Recommendations
API Learning: Applying Machine Learning to Manage the Rise of API Economy
WWW '18: Companion Proceedings of the The Web Conference 2018Application Programming Interface (API) exposes data and functions of a software application to third-party users. In digital business, API economy is one of the key component for determining the value of provided services. With the rise in number of ...
An API Design Process in Terms of Usability: A Case Study on Building More Usable APIs for Smart TV Platform
COMPSACW '14: Proceedings of the 2014 IEEE 38th International Computer Software and Applications Conference WorkshopsProducts are released based on various platforms. An Application programing interface (API) is important to develop platform based applications effectively. Previously, we had some difficulties in developing applications using our platform APIs. Their ...
The OWL API: A Java API for OWL ontologies
We present the OWL API, a high level Application Programming Interface (API) for working with OWL ontologies. The OWL API is closely aligned with the OWL 2 structural specification. It supports parsing and rendering in the syntaxes defined in the W3C ...
Comments