www.computer.org/software What Makes APIs Hard to Learn? Answers from Developers Martin P. Robillard Vol. 26, No. 6 November/December 2009 This material is presented to ensure timely dissemination of scholarly and technical work. Copyright and all rights therein are retained by authors or by other copyright holders. All persons copying this information are expected to adhere to the terms and constraints invoked by each author's copyright. In most cases, these works may not be reposted without the explicit permission of the copyright holder. © 2009 IEEE. Personal use of this material is permitted. However, permission to reprint/republish this material for advertising or promotional purposes or for creating new collective works for resale or redistribution to servers or lists, or to reuse any copyrighted component of this work in other works must be obtained from the IEEE. For more information, please see www.ieee.org/web/publications/rights/index.html. focuscooperative and human aspects of SE What Makes APIs Hard to Learn? Answers from Developers Martin P. Robillard, McGill University ost software projects reuse components exposed through APIs. In fact, A study of obstacles current-day software development technologies are becoming inseparable that professional from the large APIs they provide. To name two prominent examples, both Microsoft developers the Java Software Development Kit and the .NET framework ship with faced when learning MAPIs comprising thousands of classes supporting tasks that range from reading files to to use APIs uncovered managing complex process workflows. challenges and An API is the interface to implemented func- and interviewing developers about the obstacles resulting implications tionality that developers can access to perform they faced learning APIs, I discovered many is- for API users various tasks. APIs support code reuse, provide sues that complement those mentioned in API de- high-level abstractions that facilitate program- sign textbooks and articles. In particular, I found and designers. ming tasks, and help unify the programming ex- that API learning resources are critically impor- perience (for example, by providing a uniform tant when considering obstacles to learning the way to interact with list structures). However, API, and as worthy of attention as the structural APIs have grown very large and diverse, which aspects of the API. I also elicited specific relation- has prompted some to question their usability.1 ships between resources and API usage that API It would be a pity if the difficulty of using APIs designers and documentation writers shouldn’t would nullify the productivity gains they offer. To overlook when designing API documentation. ensure that this doesn’t happen, we need to know First, information about the high-level design of what makes APIs hard to learn. the API is necessary to help developers choose Common sense indicates that an API’s struc- among alternative ways to use the API, to struc- ture can impact its usability (see the “API Usabil- ture their code accordingly, and to use the API as ity” sidebar).2 This intuition is reflected by efforts efficiently as possible. Second, code examples can to flesh out sound design principles for APIs and become more of a hindrance than a benefit when empirical studies on the impact of design structure there’s a mismatch between the tacit purpose of on API usability.3–5 However, APIs don’t exist in the example and the goal of the example user. isolation, and other factors can also affect how de- Finally, some design decisions can influence the velopers experience them. So, what exactly does behavior of the API in subtle ways that confuse make an API hard to learn? developers. To answer this question, I investigated the ob- stacles professional developers at Microsoft faced Survey Design when learning how to use APIs. As opposed to In February and March 2009, I conducted a sur- previous API usability studies that focused on spe- vey to gather information about developers’ ex- cific design aspects, I used an approach completely periences learning APIs. Specifically, I sought grounded in developers’ experience. By surveying to identify areas of concern and themes worthy 0740-7459/09/$26.00 © 2009 IEEE November/December 2009 IEEE SOFTWARE 27 API Usability velopers, testers, and program managers. For the purpose of the survey, I considered all employees This article focuses on the obstacles to learning an API. Although learnabil- whose title implies software development as de- ity is only one dimension of usability, there’s a clear relationship between the velopers, but excluded testing engineers due to the two, in that difficult-to-use APIs are likely to be difficult to learn as well. Many specialized nature of their work. API usability studies focus on situations where developers are learning to use Because the survey also served to recruit par- an API. www.apiusability.org provides an extensive list of resources on API ticipants for in-person interviews, the sampling usability, including additional references to studies not mentioned here due to frame6 I used was the list of all Microsoft devel- space limitations. opers working at Microsoft’s Redmond, Wash., campus. This sampling frame includes many thousands of professional developers. From this of detailed investigation (as opposed to produc- pool, I randomly selected 1,000 and sent them a ing generalizable descriptive statistics). To ensure link to the survey. Targeted developers had two that I didn’t bias the results with preconceptions weeks to complete it. about obstacles I thought developers would face, I left the main questions open-ended. The survey Survey Respondents consisted of 13 questions, with the initial three A total of 83 developers answered the survey. assessing the respondent’s professional experi- However, three respondents didn’t provide an- ence. To focus the survey’s answers and get the swers to the six open questions on strategies and developers thinking about specifics, the remain- obstacles, so I discarded their responses. Despite der asked them to comment on their most recent the response rate of 8 percent, the set of respon- learning experiences with a publicly released API. dents constituted an excellent representation of The survey’s core consisted of a three-part, the target population, cutting across job titles, se- open-ended question on the obstacles developers niority levels, and technology use. faced learning APIs: Figure 1 shows the distribution of respondents across job titles and the corresponding distribu- What obstacles made it difficult for you to tion of job titles across the population (Redmond learn the API? Obstacles can have to do developers). The four leftmost bar groups repre- with the API itself, with your background, sent four seniority levels for software develop- with learning resources, etc. List the three ment engineers (SDEs). Each bar group repre- most important obstacles, in order of impor- sents a distinct job title with different associated tance (1 being the biggest obstacle). Please responsibilities. The following four bar groups be more specific than the general categories represent job titles in development management mentioned here. (lead SDEs). Although technically a management position, lead SDEs are typically involved in ac- I formatted this question as three comment tive software development along with their team. boxes. Respondents could fill in any number of The next two bar groups represent seniority lev- boxes, from none to all three. In addition, the els for architects, a multidisciplinary role involv- survey asked for information intended to help in- ing both program management and software de- terpret the respondent’s answers and discover his velopment. Finally, the population also included or her API learning strategies. I gathered con- a small fraction of developers with other titles text through seven questions on the specific API (typically specialists in areas such as security learned, the time frame, familiarity with the ap- and user experience), but I didn’t get respondents plication domain, and so on. Three questions from this pool. Among general job categories, ti- on learning strategies asked how developers ap- tles run left to right, from junior to senior. proached learning the API and were formatted in As the figure shows, respondents’ distribution the same style as the obstacle question. across job titles in the sample closely maps that of The survey concluded by asking for additional the population. Across all job titles, respondents comments and if respondents would be willing to had on average 12.9 years of professional experi- participate in future research. ence (self-reported). The median was 10 years, and 90 percent reported four of more years of profes- Population and Sample sional experience. The respondents also reported The survey targeted software developers at Mi- on their aggregated experience learning 54 distinct crosoft. Microsoft’s software development staff APIs covering a wide span of technologies, abstrac- consists of roughly 30,000 engineers, mostly de- tion levels, and application domains. Examples of 28 IEEE SOFTWARE www.computer.org/software 40 28 35 30 21 25 20 15 Sample Ratio to total (%) 15 Population 10 5 4 5 2 2 2 1 0 0 0 Software dev. engineers (SDEs) Lead SDEs Architects Other Novice Senior Novice Senior Novice Senior Job title Figure 1. Distribution of APIs the respondents reported learning included of 74 respondents mentioned at least one obstacle. respondents across job one that provides access to personal information I associated respondents with categories when they titles. Most respondents manager data on Windows mobile-based devices, indicated at least one obstacle in that category. For (49 percent) were classic windowing APIs, and Microsoft’s most re- example, 50 (out of 74) respondents mentioned at developers with junior cent Web application development platform. least one obstacle relating to API resources. Some or intermediate job responses pertained to multiple categories.