A Design Guide for Usable Web APIs
Maribel TELLO-RODRÍGUEZ,
Jorge Octavio OCHARÁN-HERNÁNDEZ,
Juan Carlos PÉREZ-ARRIAGA,
Xavier LIMÓN,
Ángel J. SÁNCHEZ-GARCÍA https://doi.org/10.15514/ISPRAS-2021-33(1)-12
Abstract
Cloud computing trends such as Software as a Service (SaaS) enable providers to host complex applications over the Internet, making them available to external consumers through an Application Programming Interface (API). The success of a SaaS, and in some sense any distributed system, is greatly influenced by its API. Highly usable APIs improve the efficiency of the development process and its quality, ensuring that programmers continue to appreciate other aspects of the API while increasing their productivity. Different studies state that the design phase within the development process of an API is the most appropriate to address usability issues. Therefore, usability should be considered as an explicit criterion in the design of an API. In this paper, we propose a design guide for web APIs with an emphasis on usability, using the best practices of usable web APIs design. Our design guide is based on an adaptation of the design science research methodology (DSRM), and it is complemented with a systematic literature review and gray literature analysis concerning methods, techniques, and tools used to develop usable APIs.
About the Authors
Maribel TELLO-RODRÍGUEZ
Universidad Veracruzana
Mexico
Bachelor in Software Engineering
Mexico
Bachelor in Software Engineering
Jorge Octavio OCHARÁN-HERNÁNDEZ
Universidad Veracruzana
Mexico
Doctor in Computing Sciences, Professor at the School of Statistics and Informatics
Mexico
Doctor in Computing Sciences, Professor at the School of Statistics and Informatics
Juan Carlos PÉREZ-ARRIAGA
Universidad Veracruzana
Mexico
Master in Computer Science, Software Developer
Mexico
Master in Computer Science, Software Developer
Xavier LIMÓN
Universidad Veracruzana
Mexico
Doctor of Artificial Intelligence, Associate Professor of the Statistics and Informatics Faculty
Mexico
Doctor of Artificial Intelligence, Associate Professor of the Statistics and Informatics Faculty
Ángel J. SÁNCHEZ-GARCÍA
Universidad Veracruzana
Mexico
Doctor of Artificial Intelligence, Full-time Professor of the Faculty of Statistics and Informatics
Mexico
Doctor of Artificial Intelligence, Full-time Professor of the Faculty of Statistics and Informatics
References
1. Espinha T., Zaidman A., Gross H.G. Web API growing pains: Loosely coupled yet strongly tied. Journal of Systems and Software, vol. 100, 2015, pp. 27-43.
2. Зосимов В.В., Христодоров А.В., Булгакова А.С. Программные решения для динамического изменения пользовательского интерфейса на основе автоматически собранной информации о пользователе. Труды ИСП РАН, том 30, вып. 3, 2018 г., стр. 207-220. DOI:10.15514/ISPRAS-2018-30(3)-1 / Zosimov V.V., Khrystodorov O.V., Bulgakova O.S. Dynamically Changing User Interfaces: Software Solutions Based on Automatically Collected User Information. Programming and Computer Software, vol. 44, no. 6, 2018, pp. 492-498 (2018).
3. Biehl M. API Architecture: The Big Picture for Building APIs. CreateSpace, 2015, 107 p.
4. Mulloy B. Web API Design – Crafting Interfaces that Developers Love. Apigee, 2012, 36 p.
5. Jin B., Sahni S., Shevat A. Designing Web APIs: Building APIs That Developers Love. O'Reilly Media, 2018, 232 p.
6. ISO/IEC 25010:2011(en). Systems and software engineering – Systems and software Quality Requirements and Evaluation (SQuaRE) – System and software quality models. 2011.
7. Speicher M. What is Usability? A Characterization based on ISO 9241-11 and ISO/IEC 25010. arXiv:1502.06792, 2015, 10 p.
8. Piccioni M., Furia C.A., Meyer B. An empirical study of API usability. In Proc. of the ACM/IEEE International Symposium on Empirical Software Engineering and Measurement, 2013, pp. 5-14.
9. Gerken J., Jetter H.C., Zöllner M., Mader M., Reiterer H. The concept maps method as a tool to evaluate the usability of APIs. In Proc. of the SIGCHI Conference on Human Factors in Computing Systems, 2011, pp. 3373-3382.
10. Henning M. API design matters. Communications of the ACM, vol. 52, no. 5, 2009, pp. 46–56.
11. Myers B.A., Stylos J. Improving API usability. Communications of the ACM, vol. 59, no. 6, 2016, pp. 62-69.
12. Zibran M.F., Eishita F.Z., Roy C.K. Useful, but usable? Factors affecting the usability of APIs. In Proc. of the 18th Working Conference on Reverse Engineering, 2011, pp. 151–155.
13. Bhaskar R.K., Anslow C., Brosz J., Maurer F. Developing usable APIs with XP and cognitive dimensions. In Proc. of the IEEE Symposium on Visual Languages and Human-Centric Computing, 2016, pp. 101–105.
14. Peffers K., Tuunanen T., Rothenberger M.A., Chatterjee S. A Design Science Research Methodology for Information Systems Research. Journal of Management Information Systems, vol. 24, issue 3, 2007, pp. 45-77.
15. Tello-Rodríguez M., Ocharán-Hernández J.O., Pérez-Arriaga J.C., Estadística F. De, Veracruzana U. Hacia una guía de diseño para APIs Web con un enfoque en la usabilidad. Abstraction & Application, vol. 25, 2019, pp. 36-60 (in Spanish).
16. Hunter K.L. Irresistible APIs: Designing web APIs that developers will love. Manning Publications, 2016, 232 p.
17. Eassa A.M., Elhoseny M., El-Bakry H.M., Salama A.S. NoSQL Injection Attack Detection in Web Applications Using RESTful Service. Programming and Computer Software, vol. 44, vol. 6, 2018, pp. 435-444.
18. Stylos J., Graf B. et al. A case study of API redesign for improved usability In Proc. of the IEEE Symposium on Visual Languages and Human-Centric Computing, 2008, pp. 189-192.
19. Lee S., Lee S., Lim S. et al. An API design process in terms of usability: A case study on building more usable apis for smart TV platform. In Proc. of the IEEE 38th International Computer Software and Applications Conference Workshops, 2014, pp.567-571.
20. Ramakrishnan L., Poon S., Hendrix V. et al. Experiences with user-centered design for the tigres workflow API. In Proc. of the IEEE 10th International Conference on e-Science, 2014, pp. 290-297.
21. Robillard M.P., Deline R. A field study of API learning obstacles. Empirical Software Engineering, vol. 16, 2011, pp.703-732.
22. Watson R. Applying the Cognitive Dimensions of API Usability to Improve API Documentation Planning. In Proc. of the 32nd ACM International Conference on The Design of Communication, 2014, pp. 1-2.
23. . Sohan S.M., Maurer F., Anslow C., Robillard M.P. A study of the effectiveness of usage examples in REST API documentation. In Proc. of the IEEE Symposium on Visual Languages and Human-Centric Computing, 2017, pp. 53-61.
24. Macvean A., Maly M., Daughtry J. API Design Reviews at Scale. In Proc. of the Conference Extended Abstracts on Human Factors in Computing Systems, 2016, pp. 849-858.
25. Robillard M.P. What Makes APIs Hard to Learn? Answers from Developers. IEEE Software, vol. 26, no. 6, 2009, pp. 27-34,
26. . Munir M.B., Mushtaq A. A framework for extending usability engineering: API usability essentials: Extending usability via component-based platform. In Proc. of the IEEE Conference on Open Systems, 2012, pp. 1-6.
27. Kitchenham B., Pretorius R., Budgen D. et al. Systematic literature reviews in software engineering-A tertiary study Information and Software Technology, volume 52, issue 8, 2010, pp. 792-805.
28. Stylos J., Myers B.A. The implications of method placement on API learnability. In Proc. of the 16th ACM SIGSOFT International Symposium on Foundations of software engineering, 2008, pp. 105-112.
29. Pearson A. Balancing the evidence: incorporating the synthesis of qualitative data into systematic reviews. JBI Reports, vol. 2, issue 2, 2004, pp. 45–64.
30. O’Callaghan P., O’Callaghan P. The API Walkthrough Method: A Lightweight Method for Getting Early Feedback about an API. In Proc. of the Workshop on Evaluation and Usability of Programming. Languages and Tools, 2010, pp. 1-6.
31. Farooq U., Welicki L., Zirkler D. API Peer Reviews: A Method for Evaluating Usability of Application Programming Interfaces. In Proc. of the ACM Conference on Computer Supported Cooperative Work, 2010, pp. 207–210.
32. Mitra R. Rapido : A Sketching Tool for Web API Designers. In Proc. of the 24th International Conference on World Wide Web, 2015, pp. 1509–1514.
33. Murphy-Hill E., Sadowski C., Head A. et al. Discovering API Usability Problems at Scale. In Proc. of the 2nd International Workshop on API Usage and Evolution, 2018, pp. 14-17.
34. Beaton J.K.K., Myers B.A.A., Stylos J. et al. Usability Evaluation for Enterprise SOA APIs. In Proc. of the 2nd International Workshop on Systems Development in SOA Environments, 2008, pp. 29–34.
35. Zghidi A., Hammouda I., Hnich B. Towards a formal API assessment. In Proc. of the 40th International Conference on Software Engineering: Companion Proceeedings, 2018, pp. 398–399.
36. Scheller T., Kühn E. Automated measurement of API usability: The API Concepts Framework. Information and Software Technology, vol. 61, 2015, pp. 145-162.
37. López-Fernández L., García B., Gallego M., Gortázar F.: Designing and evaluating the usability of an API for real-time multimedia services in the Internet. Multimedia Tools and Applications, vol. 76, 2017, pp. 14247–14304.
38. Arquitectura y estrategia de API Un enfoque coordinado. White paper. CA technologies, 2015, 23 p. (in Spanish).
39. Wiegers K., Beatty J. Software Requirements (Developer Best Practices), 3rd Edition. Microsoft Press, 2013, 672 p.
40. Mosqueira-Rey E., Alonso-Ríos D. et al. A systematic approach to API usability: Taxonomy-derived criteria and a case study. Information and Software Technology, vol. 97, 2018, pp. 46-63.
41. Lauret A. The Design of Web APIs. Manning Publications, 2019, 392 p.
42. Webber J., Parastatidis S., Robinson I. REST in Practice: Hypermedia and Systems Architecture. O’Reilly Media, 2010, 448 p.
Review
For citations:
TELLO-RODRÍGUEZ M., OCHARÁN-HERNÁNDEZ J., PÉREZ-ARRIAGA J., LIMÓN X., SÁNCHEZ-GARCÍA Á.J. A Design Guide for Usable Web APIs. Proceedings of the Institute for System Programming of the RAS (Proceedings of ISP RAS). 2021;33(1):173-188. (In Russ.) https://doi.org/10.15514/ISPRAS-2021-33(1)-12
Email this article 