API Usability

An overview article about API Usability in general!

Brad A. Myers and Jeffrey Stylos, "Improving API Usability", Communications of the ACM, vol 59, No. 6, June, 2016, pp. 62-69.

Brad Myers gave a talk on "Human-Centered Methods for Improving API Usability" at Stanford on October 27, 2017. See the Talk announcement and YouTube video of talk.

Whether creating a piece of desktop software, writing applications for handheld devices, using web services or middleware, or scripting the Web, the use of application programming interfaces (APIs) in modern software development is ubiquitous. These APIs, also called software development kits (SDKs), toolkits, web services, middleware, frameworks, or libraries, are often large, complex, and broad in scope, containing many hundreds or thousands of classes and interfaces. A typical developer may use only a small portion of the total functionality of an API, but learning even that subset can be a daunting task for new programmers.

API designers must consider many factors when creating an API, such as the deveoper's use cases, class granularity, level of abstraction, consistency with other APIs, etc. Research has also shown that designing APIs carefully for their intended audience improves usability. APIs are valuable and important to companies' income, yet are rarely evaluated for usability.

We are investigating many aspects of how to evaluate and improve the usability of APIs. We are studying the implications of choosing particular API design patterns on programmer productivity and API learning, the needs of API Designers, guidelines for designing REST APIs, usability issues with specific APIs, the interactions between security and usability of APIs, and new tools and documentation techniques that help when it is not possible to revise the API itself.

Web Services

A current focus, funded by grants from Google, is on REST APIs and web services in general. We analyzed the guidelines published for REST APIs, and identified issues that API designers reported. We are studying the usability of the Apache Beam API for parallel computation on big data in the cloud, and created a plugin called Alabaster to help with the Python SDK for Beam.

preprint

Lauren Murphy, Mary Beth Kery, Tosin Alliyu, Andrew Macvean and Brad A. Myers, "API Designers in the Field: Design Practices and Challenges for Creating Usable APIs", 2018 IEEE Symposium on Visual Languages and Human-Centric Computing (VL/HCC'18), October 1 - 4, 2018, Lisbon, Portugal. To appear.

local

Lauren Murphy, Tosin Alliyu, Mary Beth Kery, Andrew Macvean, Brad A. Myers. "Preliminary Analysis of REST API Style Guidelines". 8th Workshop on Evaluation and Usability of Programming Languages and Tools (PLATEAU'2017) at SPLASH 2017. 23 Oct 2017, Vancouver, BC.

API Usability and Security

We received an NSF grant (CNS-1423054) and a grant from the Software Engineering Institute (SEI) to study the interactions between making an API more usable and making it more secure. In some cases, these appear to be in concert (making the API more usable makes it easier to use correctly, so there are fewer security errors), and in other cases, security and usability seem to be in conflict. See also the SEI's CERT Secure Coding Initiative section on API Usability and Security.


Michael Coblenz, Jonathan Aldrich, Brad Myers and Joshua Sunshine, "Interdisciplinary Programming Language Design", Onward! 2018 Essays, at SPLASH 2018, November 4-9, 2018, Boston, MA. To appear.

local

Michael Coblenz, Jonathan Aldrich, Joshua Sunshine, Brad A. Myers, "User-Centered Design of Permissions, Typestate, and Ownership in the Obsidian Blockchain Language," HCI for Blockchain: Studying, Designing, Critiquing and Envisioning Distributed Ledger Technologies Workshop at CHI'2018, April 22, 2018, Montreal, QC, Canada.

local

Celeste Barnaby, Michael Coblenz, Tyler Etzel, Eliezer Kanal, Joshua Sunshine, Brad Myers, Jonathan Aldrich. "A User Study to Inform the Design of the Obsidian Blockchain DSL." 8th Workshop on Evaluation and Usability of Programming Languages and Tools (PLATEAU'2017) at SPLASH 2017. 23 Oct 2017.

ieee
local

Sam Weber, Michael Coblenz, Brad Myers, Jonathan Aldrich, Joshua Sunshine. "Empirical Studies on the Security and Usability Impact of Immutability," IEEE Secure Development Conference (SecDev'2017), September 24-26, 2017, Cambridge, MA. pp. 50-53.

acm Local

Michael Coblenz, Whitney Nelson, Jonathan Aldrich, Brad Myers and Joshua Sunshine, "Glacier: Transitive Class Immutability for Java", ICSE'2017: The 39th International Conference on Software Engineering, Buenos Aires, Argentina, May 20-28, 2017. pp. 496-506.

acm
local

Michael Coblenz, Joshua Sunshine, Jonathan Aldrich, Brad Myers, Sam Weber, Forrest Shull, "Exploring Language Support for Immutability" ICSE'2016: The 38th International Conference on Software Engineering, Austin, TX, May 14 - 22, 2016. pp. 736-747.

local

Michael Coblenz, Robert Seacord, Brad Myers, Joshua Sunshine and Jonathan Aldrich, "A Course-Based Usability Analysis of Cilk Plus and OpenMP", 2015 IEEE Symposium on Visual Languages and Human-Centric Computing (VL/HCC'15), October 18–22, 2015, Atlanta, Georgia. pp. 245-249.

poster

Brad A. Myers, Sam Weber, Robert Seacord, Michael Coblenz, Whitney Nelson, Jonathan Aldrich, and Joshua Sunshine, "TWC: Small: Empirical Evaluation of the Usability and Security Implications of Application Programming Interface Design" (Poster), National Science Foundation Secure and Trustworthy Cyberspace (SaTC) Principal Investigators' Meeting (SaTCPI'17), January 9-11, 2017, Arlington, VA.

poster

Brad A. Myers, Sam Weber, and Robert Seacord, Michael Coblenz, David Keaton, Forrest J. Shull, Joshua Sunshine, Robert Schiela, "TWC: Small: Empirical Evaluation of the Usability and Security Implications of Application Programming Interface Design" (Poster), National Science Foundation Secure and Trustworthy Cyberspace (SaTC) Principal Investigators' Meeting (SaTCPI'15), January 5-7, 2015, Arlington, VA

local
slides

Sam Weber, Robert Seacord, Forrest Shull, David Keaton, Brad Myers, Michael Coblenz, "Empirical Evaluation of API Usability and Security", Layered Assurance Workshop, December 8, 2014, New Orleans, LA. p. 35.

ACM
local

Michael Coblenz, Jonathan Aldrich, Brad Myers and Josh Sunshine. "Considering Productivity Effects of Explicit Type Declarations", The Fifth Workshop on Evaluation and Usability of Programming Languages and Tools (PLATEAU 2014), at SPLASH 2014, 21 Oct 2014, Portland, OR. pp. 59-61.

Thesis

Jeff Stylos's PhD dissertation includes much of this research that happened between 2006 and 2010.

local

Jeffrey Stylos. Making APIs More Usable with Improved API Designs, Documentation and Tools. PhD dissertation, May, 2009. Carnegie Mellon Computer Science Department Technical Report No. CMU-CS-09-130.

Studies of APIs

Local

Lauren Murphy, Tosin Alliyu, Mary Beth Kery, Andrew Macvean, Brad A. Myers. Preliminary Analysis of REST API Style Guidelines. 8th Workshop on Evaluation and Usability of Programming Languages and Tools (PLATEAU'2017) at SPLASH 2017. 23 Oct 2017.

local

John M. Daughtry, Jeffrey Stylos, Umer Farooq, Brad A. Myers (2009). API Usability: CHI'2009 Special Interest Group Meeting, Extended Abstracts, CHI'2009, Boston, MA, April 4-9, 2009. pp. 2771-2774.

local

Stylos, J., Myers, B. (2008). The Implications of Method Placement on API Learnability. Sixteenth ACM SIGSOFT Symposium on Foundations of Software Engineering, FSE 2008. Atlanta, GA, November 9-14, 2008. pp. 105-112.

local

Stylos, J., Myers, B. (2007). Mapping the Space of API Design Decisions. IEEE Symposium on Visual Languages and Human-Centric Computing, VL/HCC'07. Sept 23-27, 2007, Coeur d'Alene, Idaho. pp. 50-57.

local

Ellis, B., Stylos J., Myers B. (2007). The Factory Pattern in API Design: A Usability Evaluation. International Conference on Software Engineering, Minneapolis, MN, USA, May 20-26, pp. 302-312.

local

Stylos J, Clarke S. (2007). Usability Implications of Requiring Parameters in Objects' Constructors. International Conference on Software Engineering, Minneapolis, MN, USA, May 20-26, pp. 529-539.

Tools to help with APIs

(Note that each of these tools have their own pages: Dacite, Graphite, Calcite, Jadeite, Apatite, Mica, Euklas, Alabaster).

DOI
local

André L. Santos and Brad A. Myers, Design Annotations to Improve API Discoverability. 2015, (DACITE), The Journal of Systems & Software, volume 126, April, 2017, Pages 17–33.

ACM
local

Christian Dörner, Andrew Faulring, Brad A. Myers. "EUKLAS - Supporting Copy-and-Paste Strategies for Integrating Example Code", The Fifth Workshop on Evaluation and Usability of Programming Languages and Tools (PLATEAU 2014), at SPLASH 2014, 21 Oct 2014, Portland, OR. pp. 13-20.

local movie

Cyrus Omar, YoungSeok Yoon, Thomas D. LaToza, Brad A. Myers, Active Code Completion. ICSE'2012: 34nd International Conference on Software Engineering, Zurich, Switzerland, 2-9 June 2012. pp. 859-869.

ieee
local

Mathew Mooty, Andrew Faulring, Jeffrey Stylos and Brad Myers. Calcite: Completing Code Completion for Constructors using Crowds, 2010 IEEE Symposium on Visual Languages and Human-Centric Computing (VL/HCC'10), Leganes-Madrid, Spain, 21-25 September 2010. pp. 15-22.

ieee
local

Daniel S. Eisenberg, Jeffrey Stylos, Andrew Faulring, Brad A. Myers. Using Association Metrics to Help Users Navigate API Documentation, 2010 IEEE Symposium on Visual Languages and Human-Centric Computing (VL/HCC'10), Leganes-Madrid, Spain, 21-25 September 2010. pp. 23-30.

local
movie

Daniel S. Eisenberg, Jeffrey Stylos, and Brad A. Myers, Apatite: A New Interface for Exploring APIs, Proceedings CHI'2010: Human Factors in Computing Systems. Atlanta, GA, April 10-15, 2010. pp. 1331-1334.

ieee
local

Jeffrey Stylos, Andrew Faulring, Zizhuang Yang, Brad A. Myers. Improving API Documentation Using API Usage Information. 2009 IEEE Symposium on Visual Languages and Human-Centric Computing, VL/HCC'09, Sept. 20-24, 2009. Corvallis, Oregon. pp. 119-126.

local

Jeffrey Stylos, Brad A. Myers, Zizhuang Yang. (2009) Jadeite: Improving API Documentation Using Usage Information. Extended Abstracts, CHI'2009, (Work in Progress Poster). Boston, MA, April 4-9, 2009. pp. 4429-4434.

local

Stylos, J. and Myers, B. A. (2006) Mica: A Web-Search Tool for Finding API Components and Examples. IEEE Symposium on Visual Languages and Human-Centric Computing, Brighton, UK, September 5-7, 195-202.

Usability of SAP's APIs

As a subproject, we had a long and fruitful collaboration with SAP to improve the usability of various of their APIs and programmer tools, including their Enterprise Service Oriented Architecture (eSOA) APIs, their IDE for the SAP NetWeaver Gateway, and their HANA tools and APIs. SAP's eSOA usability effort faced interesting and novel challenges. By examining the APIs and tools that are part of the eSOA life cycle, we identified pain points, barriers and means of improvement relevant to eSOA APIs and other domains as well. For the NetWeaver Gateway, we used HCI techniques to evaluate and iteratively improve the IDE. And for HANA, we evaluated how to improve the developer experience.

Here is a nice letter from 2009 from Dr. Klaus Weber, Executive Vice President, Business Suite Extensions, SAP AG, about our work with SAP (html).

local

Andrew Faulring, Brad A. Myers,Yaad Oren, Keren Rotenberg. A Case Study of Using HCI Methods to Improve Tools for Programmers. Cooperative and Human Aspects of Software Engineering (CHASE), An ICSE 2012 Workshop. Zurich, Switzerland, June 2, 2012. pp. 37-39.

igi

Brad A. Myers, Sae Young Jeong, Yingyu Xie, Jack Beaton, Jeff Stylos, Ralf Ehret, Jan Karstens, Arkin Efeoglu, Daniela K. Busse. Studying the Documentation of an API for Enterprise Service-Oriented Architecture. The Journal of Organizational and End User Computing, JOEUC, a publication of the Information Resources Management Association, IGI Publishing. Special Issue on End-User Development. vol. 22, no. 1, Jan-Mar, 2010. pp. 23-51. DOI: 10.4018/joeuc.2010101903.

local

Jeong, S., Xie, Y., Beaton, J., Myers, B., Stylos, J., Ehret, R., Karstens, J., Efeoglu, A., Busse, D. (2009). Improving Documentation for eSOA APIs Through User Studies. Second International Symposium on End User Development (IS-EUD'2009), March 2-4, 2009. Siegen, Germany. Springer-Verlag, LNCS 5435, pp. 86-105.

local

Stylos, J., Graf, B., Busse, D., Ziegler, C., Ehret, R., Karstens, J. (2008). A Case Study of API Redesign for Improved Usability. IEEE Symposium on Visual Languages and Human-Centric Computing, VL/HCC'08. Sept 15-19, 2008, Herrsching am Ammersee, German. pp. 189-192.

local

Beaton, J., Jeong, S., Xie, Y., Stylos, J., Myers, B. (2008). Usability challenges for enterprise service-oriented architecture APIs. IEEE Symposium on Visual Languages and Human-Centric Computing, VL/HCC'08. Sept 15-19, 2008, Herrsching am Ammersee, German. pp. 193-196.

local

Beaton, J., Myers, B., Stylos, J., Jeong, S., Xie, Y. (2008). Usability Evaluation for Enterprise SOA APIs. 2nd International Workshop on Systems Development in SOA Environments, SDSOA 2008, Co-located with ICSE 2008, Leipzig, Germany. May 12, 2008. pp. 29-34.

Funding

Our API Usability research has been funded by generous grants from SAP (2007-2011), CMU's Software Engineering Institute (2014-2015), the NSF (grant CNS-1423054 and its REU supplements - 2014-2018), and Google (2017-2019).

[Any opinions, findings and conclusions or recommendations expressed in this material are those of the author(s) and do not necessarily reflect those of the National Science Foundation or any other sponsor.]

External Links

  • APIUsability.org is collecting resources on people, papers, events, and talks about API Usability.

  • Copyright © 1996-2018 - Carnegie Mellon University - All Rights Reserved.