research-article

On the Support for Designing a Conversational Software API: An Action Research Study: An Action Research Study

Authors:

Alessandro GarciaAuthors Info & Claims

SBES '23: Proceedings of the XXXVII Brazilian Symposium on Software Engineering

Pages 57 - 66

https://doi.org/10.1145/3613372.3613400

Published: 25 September 2023 Publication History

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.

References

[1]

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 ….

[2]

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.

[3]

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.

Digital Library

[4]

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.

Digital Library

[5]

John M Carroll. 2000. Making use: scenario-based design of human-computer interactions. MIT press.

Digital Library

[6]

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.

[7]

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_2

[8]

Clarisse Sieckenius De Souza. 2005. The semiotic engineering of human-computer interaction. MIT press.

[9]

Herbert P Grice. 1975. Logic and Conversation. In Speech acts. Brill, 41–58.

[10]

Michi Henning. 2007. API Design Matters. Queue 5, 4 (May 2007), 24–36. https://doi.org/10.1145/1255421.1255422

Digital Library

[11]

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.3025827

Digital Library

[12]

Open API Initiative. 2020. OpenAPI Specification. http://spec.openapis.org/oas/v3.0.3#fixed-fields-8

[13]

Maxime Lamothe and Weiyi Shang. 2020. When APIs are Intentionally Bypassed: An Exploratory Study of API Workarounds. (2020), 13.

[14]

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.

Digital Library

[15]

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.2897610

Digital Library

[16]

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.010

[17]

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.

[18]

Brad A Myers and Jeffrey Stylos. 2016. Improving API usability. Commun. ACM 59, 6 (2016), 62–69. Publisher: ACM New York, NY, USA.

Digital Library

[19]

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.

[20]

Sebastian Nielebock, Robert Heumüller, Jacob Krüger, and Frank Ortmeier. 2020. Cooperative API Misuse Detection Using Correction Rules. (2020), 4.

[21]

Jakob Nielsen. 1994. Usability Engineering. Morgan Kaufmann. Google-Books-ID: 95As2OF67f0C.

Digital Library

[22]

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.002

Digital Library

[23]

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.

Digital Library

[24]

Mary Beth Rosson and John M. Carroll. 2002. Usability Engineering: Scenario-Based Development of Human-Computer Interaction. Morgan Kaufmann. Google-Books-ID: sRPg0IYhYFYC.

[25]

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.1570489

Digital Library

[26]

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-4

[27]

UML Specification. [n. d.]. About the Unified Modeling Language Specification Version 2.5.1. https://www.omg.org/spec/UML/

[28]

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.92

Digital Library

[29]

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.1453117

Digital Library

[30]

Michel Thiollent. 1996. Metodologia da pesquisa–ação (7ª edição). São Paulo-SP.

[31]

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.2666239

Digital Library

[32]

Gerald M Weinberg. 1971. The Psychology of Computer Programming. Vol. 29. Van Nostrand Reinhold New York.

[33]

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.3062386

Digital Library

[34]

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.

Cited By

D. M. Bastos JDe Mello RFabricio Garcia A(2025)Colloquy: Evidence-Based Method for Supporting the Design of Conversational APIsJournal of Software Engineering Research and Development10.5753/jserd.2024.413012:1Online publication date: 18-Feb-2025
https://doi.org/10.5753/jserd.2024.4130

Index Terms

On the Support for Designing a Conversational Software API: An Action Research Study: An Action Research Study
1. Human-centered computing
  1. Interaction design
    1. Interaction design process and methods
2. Software and its engineering
  1. Software creation and management
    1. Software development techniques

Recommendations

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 ...
API documentation and software community values: a survey of open-source API documentation
SIGDOC '13: Proceedings of the 31st ACM international conference on Design of communication

Studies of what software developers need from API documentation have reported consistent findings over the years; however, these studies all used similar methods--usually a form of observation or survey. Our study looks at API documentation as artifacts ...
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 Workshops

Products 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 ...

Comments

Information & Contributors

Information

Published In

cover image ACM Other conferences

SBES '23: Proceedings of the XXXVII Brazilian Symposium on Software Engineering

September 2023

570 pages

ISBN:9798400707872

DOI:10.1145/3613372

Copyright © 2023 ACM.

Permission to make digital or hard copies of all or part of this work for personal or classroom use is granted without fee provided that copies are not made or distributed for profit or commercial advantage and that copies bear this notice and the full citation on the first page. Copyrights for components of this work owned by others than the author(s) must be honored. Abstracting with credit is permitted. To copy otherwise, or republish, to post on servers or to redistribute to lists, requires prior specific permission and/or a fee. Request permissions from [email protected].

Publisher

Association for Computing Machinery

New York, NY, United States

Publication History

Published: 25 September 2023

Permissions

Request permissions for this article.

Request Permissions

Check for updates

Author Tags

Qualifiers

Research-article
Research
Refereed limited

Conference

SBES 2023

SBES 2023: XXXVII Brazilian Symposium on Software Engineering

September 25 - 29, 2023

Campo Grande, Brazil

Acceptance Rates

Overall Acceptance Rate 147 of 427 submissions, 34%

Contributors

Other Metrics

View Article Metrics

Bibliometrics & Citations

Bibliometrics

Article Metrics

1
Total Citations
View Citations
39
Total Downloads

Downloads (Last 12 months)17
Downloads (Last 6 weeks)2

Reflects downloads up to 05 Mar 2025

Other Metrics

View Author Metrics

Citations

Cited By

D. M. Bastos JDe Mello RFabricio Garcia A(2025)Colloquy: Evidence-Based Method for Supporting the Design of Conversational APIsJournal of Software Engineering Research and Development10.5753/jserd.2024.413012:1Online publication date: 18-Feb-2025
https://doi.org/10.5753/jserd.2024.4130

View Options

Login options

Check if you have access through your login credentials or your institution to get full access on this article.

Full Access

Get this Publication

View options

PDF

View or Download as a PDF file.

eReader

View online with eReader.

HTML Format

View this article in HTML Format.

Figures

Tables

Media

View Table of Conten