Skip to main content
SpringerLink
Log in

A Design Guide for Usable Web APIs

  • Published:
Programming and Computer Software Aims and scope Submit manuscript

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.

This is a preview of subscription content, log in via an institution to check access.

Access this article

Log in via an institution

Price excludes VAT (USA)
Tax calculation will be finalised during checkout.

Instant access to the full article PDF.

Institutional subscriptions

Fig. 1.
Fig. 2.
Fig. 3.
Fig. 4.
Fig. 5.
Fig. 6.
Fig. 7.

Similar content being viewed by others

REFERENCES

  1. Espinha, T., Zaidman, A., and Gross, H.G., Web API growing pains: loosely coupled yet strongly tied, J. Syst. Software, 2015, vol. 100, pp. 27–43. https://doi.org/10.1016/j.jss.2014.10.014

    Article  Google Scholar 

  2. Zosimov, V.V., Khrystodorov, O.V., and Bulgakova, O.S., Dynamically changing user interfaces: software solutions based on automatically collected user information, Program. Comput. Software, 2018, vol. 44, pp. 492–498. https://doi.org/10.1134/S036176881806018X

    Article  Google Scholar 

  3. Biehl, M., API Architecture: the Big Picture for Building APIs, 2015.

  4. Mulloy, B., Web API Design – Crafting Interfaces That Developers Love, 2012.

  5. Jin, B., Sahni, S., and Shevat, A., Designing Web APIs, 2018.

  6. ISO/IEC 25010:2011: 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, Tech. Rep., Technische Universität Chemnitz, Department of Computer Science, 2015, no. CSR-15-02.

  8. Piccioni, M., Furia, C.A., and Meyer, B., An empirical study of API usability, Proc. ACM/IEEE Int. Symp. on Empirical Software Engineering and Measurement, Baltimore, 2013, pp. 5–14. https://doi.org/10.1109/ESEM.2013.14

  9. Gerken, J., Jetter, H.-C., Zöllner, M., Mader, M., and Reiterer, H., The concept maps method as a tool to evaluate the usability of APIs, Proc. 2011 Annu. Conf. on Human Factors in Computing Systems CHI’11, Vancouver, 2011. https://doi.org/10.1145/1978942.1979445

  10. Henning, M., API design matters, Commun. ACM, 2009, vol. 52, pp. 46–56. https://doi.org/10.1145/1506409.1506424

    Article  Google Scholar 

  11. Myers, B.A. and Stylos, J., Improving API usability, Commun. ACM, 2016, vol. 59, pp. 62–69. https://doi.org/10.1145/2896587

    Article  Google Scholar 

  12. Zibran, M.F., Eishita, F.Z., and Roy, C.K., Useful, but usable? Factors affecting the usability of APIs, Proc. Working Conf. on Reverse Engineering WCRE 2011, Limerick, 2011, pp. 151–155. https://doi.org/10.1109/WCRE.2011.26

  13. Bhaskar, R.K., Anslow, C., Brosz, J., and Maurer, F., Developing usable APIs with XP and cognitive dimensions, Proc. IEEE Symp. on Visual Languages and Human-Centric Computing (VL/HCC), Cambridge, 2016, pp. 101–105. https://doi.org/10.1109/VLHCC.2016.7739671

  14. Peffers, K., Tuunanen, T., Rothenberger, M.A., and Chatterjee, S., A design science research methodology for information systems research, J. Manag. Inf. Syst., 2007, vol. 24, no. 3, pp. 45–77. https://doi.org/10.2753/MIS0742-1222240302

    Article  Google Scholar 

  15. Tello-Rodríguez, M., Ocharán-Hernández, J.O., Pérez-Arriaga, J.C., Estadística, and F. De, Veracruzana, U., Hacia una guía de diseño para APIs Web con un enfoque en la usabilidad Towards a design guide for Web APIs with a focus on usability, Abstr. Appl., 2019, vol. 25, pp. 36–60.

    Google Scholar 

  16. Hunter, K.L., Irresistible APIs, Designing Web APIs That Developers Will Love, Manning Publ., 2017.

    Google Scholar 

  17. Eassa, A.M., Elhoseny, M., El-Bakry, H.M., and Salama, A.S., NoSQL injection attack detection in web applications using RESTful service, Program. Comput. Software, 2018, vol. 44, pp. 435–444. https://doi.org/10.1134/S036176881901002X

    Article  Google Scholar 

  18. Stylos, J., Graf, B., Busse, D.K., Ziegler, C., Ehret, R., and Karstens, J., A case study of API redesign for improved usability, Proc. IEEE Symp. on Visual Languages and Human-Centric Computing VL/HCC 2008, Ammersee, 2008, pp. 189–192. https://doi.org/10.1109/VLHCC.2008.4639083

  19. Lee, S., Lee, S., Lim, S., Jung, J., Choi, S., Kim, N., and Lee, J.B., An API design process in terms of usability: a case study on building more usable apis for smart TV platform, Proc. 38th IEEE Annu. Int. Computers, Software and Applications Conf. Workshops COMPSACW 2014, Vasteras, 2014, pp. 567–571. https://doi.org/10.1109/COMPSACW.2014.95

  20. Ramakrishnan, L., Poon, S., Hendrix, V., Gunter, D., Pastorello, G.Z., and Agarwal, D., Experiences with user-centered design for the tigres workflow API, Proc. 10th IEEE Int. Conf. eScience 2014, Guarujá, 2014, vol. 1, pp. 290–297. https://doi.org/10.1109/eScience.2014.56

  21. Robillard, M.P. and Deline, R., A field study of API learning obstacles, Empirical Software Eng, 2011, vol. 16, pp. 703–732. https://doi.org/10.1007/s10664-010-9150-8

    Article  Google Scholar 

  22. Watson, R., Applying the cognitive dimensions of API usability to improve API documentation planning, Proc. 32nd ACM Int. Conf. on Design of Communication SIGDOC’14, Colorado Springs, 2014. https://doi.org/10.1145/2666216.2666239

  23. Sohan, S.M., Maurer, F., Anslow, C., and Robillard, M.P., A study of the effectiveness of usage examples in REST API documentation, Proc. IEEE Symp. on Visual Languages and Human-Centric Computing VL/HCC 2017, Raleigh, 2017, pp. 53–61. https://doi.org/10.1109/VLHCC.2017.8103450

  24. Macvean, A., Maly, M., and Daughtry, J., API design reviews at scale, Proc. CHI Conf. Extended Abstracts on Human Factors in Computing Systems CHI EA’16, San Jose, 2016, pp. 849–858. https://doi.org/10.1145/2851581.2851602

  25. Robillard, M.P., What makes APIs hard to learn? Answers from developers, IEEE Software, 2009, vol. 26, pp. 27–34. https://doi.org/10.1109/MS.2009.193

    Article  Google Scholar 

  26. Munir, M.B. and Mushtaq, A., A framework for extending usability engineering: API usability essentials: extending usability via component-based platform, Proc. IEEE Conf. on Open Systems ICOS 2012, Kuala Lumpur, 2012. https://doi.org/10.1109/ICOS.2012.6417654

  27. Kitchenham, B., Pretorius, R., Budgen, D., Brereton, O.P., Turner, M., Niazi, M., and Linkman, S., Systematic literature reviews in software engineering – a tertiary study, Inf. Software Technol., 2010, vol. 52, no. 8, pp. 792–805. https://doi.org/10.1016/j.infsof.2010.03.006.1

    Article  Google Scholar 

  28. Pearson, A., Balancing the evidence: incorporating the synthesis of qualitative data into systematic reviews, JBI Rep., 2004, vol. 2, pp. 45–64. https://doi.org/10.1111/j.1479-6988.2004.00008.x

    Article  Google Scholar 

  29. Stylos, J. and Myers, B.A., The implications of method placement on API learnability, Proc. 16th ACM SIGSOFT Int. Symp. on Foundations of Software Engineering – SIGSOFT’08/FSE-16, Atlanta, 2008. https://doi.org/10.1145/1453101.14531173

  30. O’Callaghan, P., The API walkthrough method: a lightweight method for getting early feedback about an API, Proc. Workshop on Evaluation and Usability of Programming Languages and Tools (PLATEAU), Reno/Tahoe, 2010. https://doi.org/10.1145/1937117.1937122

  31. Farooq, U., Welicki, L., and Zirkler, D., API peer reviews: a method for evaluating usability of application programming interfaces, Proc. 2010 ACM Conf. on Computer Supported Cooperative Work, Savannah, 2010, pp. 207–210. https://doi.org/10.1145/1718918.1718957

  32. Mitra, R., Rapido: a sketching tool for web API designers, Proc. WWW 2015 Companion, Florence, May 18–22, 2015. https://doi.org/10.1145/2740908.2743040

  33. Murphy-Hill, E., Sadowski, C., Head, A., Daughtry, J., Macvean, A., Jaspan, C., and Winter, C., Discovering API usability problems at scale, Proc. IEEE/ACM 2nd Int. Workshop on API Usage and Evolution (WAPI), Gothenburg, 2018, pp. 14–17. https://doi.org/10.1145/3194793.3194795

  34. Beaton, J.K.K., Myers, B.A.A., Stylos, J., Young, S., Jeong, S.Y., and Xie, Y., Usability evaluation for enterprise SOA APIs, Proc. 2nd Int. Workshop on Systems Development in SOA Environments, Leipzig, 2008, pp. 29–34. https://doi.org/10.1145/1370916.1370924

  35. Zghidi, A., Hammouda, I., and Hnich, B., Poster: towards a formal API assessment, Proc. 40th IEEE/ACM Int. Conf. on Software Engineering: Companion (ICSE-Companion), Gothenburg, 2018, pp. 398–399. https://doi.org/10.1145/3183440.3195026

  36. Scheller, T. and Kühn, E., Automated measurement of API usability: the API concepts framework, Inf. Software Technol., 2015, vol. 61, pp. 145–162. https://doi.org/10.1016/j.infsof.2015.01.009

    Article  Google Scholar 

  37. López-Fernández, L., García, B., Gallego, M., and Gortázar, F., Designing and evaluating the usability of an API for real-time multimedia services in the Internet, Multimedia Tools Appl., 2017, vol. 76, pp. 14247–14304. https://doi.org/10.1007/s11042-016-3729-z

    Article  Google Scholar 

  38. CA technologies: Arquitectura y estrategia de API: Un enfoque coordinado, 2015.

  39. Wiegers, K. and Beatty, J., Software Requirements, 3rd ed., 2013. https://doi.org/10.3362/9781780449357

    Book  Google Scholar 

  40. Mosqueira-Rey, E., Alonso-Ríos, D., Moret-Bonillo, V., Fernández-Varela, I., and Álvarez-Estévez, D., A systematic approach to API usability: taxonomy-derived criteria and a case study, Inf. Software Technol., 2018, vol. 97, pp. 46–63. https://doi.org/10.1016/j.infsof.2017.12.010

    Article  Google Scholar 

  41. Lauret, A., The Design of Web APIs, Manning Publ., 2019.

    Google Scholar 

  42. Webber, J., Parastatidis, S., and Robinson, I., REST in Practice: Hypermedia and Systems Architecture, O’Reilly Media Inc., 2010.

    Book  Google Scholar 

Download references

ACKNOWLEDGMENTS

The authors are grateful for the support and funding granted by PRODEP 2018 (Programa para el Desarrollo Profesional Docente en Educación Superior, 48058 511-6/18-9245/PTC-888).

Author information

Authors and Affiliations

  1. School of Statistics and Informatics, Universidad Veracruzana, Av. Xalapa, Obrero Campesino, 91020, Xalapa-Enríquez, Ver., Mexico

    M. Tello-Rodríguez, J. O. Ocharán-Hernández, J. C. Pérez-Arriaga, X. Limón & Á.J. Sánchez-García

Authors
  1. M. Tello-Rodríguez
    View author publications

    You can also search for this author in PubMed Google Scholar

  2. J. O. Ocharán-Hernández
    View author publications

    You can also search for this author in PubMed Google Scholar

  3. J. C. Pérez-Arriaga
    View author publications

    You can also search for this author in PubMed Google Scholar

  4. X. Limón
    View author publications

    You can also search for this author in PubMed Google Scholar

  5. Á.J. Sánchez-García
    View author publications

    You can also search for this author in PubMed Google Scholar

Corresponding authors

Correspondence to M. Tello-Rodríguez, J. O. Ocharán-Hernández, J. C. Pérez-Arriaga, X. Limón or Á.J. Sánchez-García.

Rights and permissions

Reprints and permissions

About this article

Check for updates. Verify currency and authenticity via CrossMark

Cite this article

Tello-Rodríguez, M., Ocharán-Hernández, J.O., Pérez-Arriaga, J.C. et al. A Design Guide for Usable Web APIs. Program Comput Soft 46, 584–593 (2020). https://doi.org/10.1134/S0361768820080241

Download citation

  • Received:

  • Revised:

  • Accepted:

  • Published:

  • Issue Date:

  • DOI: https://doi.org/10.1134/S0361768820080241

Search

Navigation