The Uses of Interactive Explorers for Web APIs John Daughtry Software Engineer Google, Inc. Seattle, WA, USA daughtry@google.com Andrew Macvean User Experience Researcher Google, Inc. Seattle, WA, USA amacvean@google.com Luke Church Software Engineer Google, Inc. London, UK lukechurch@google.com Abstract Interactive method invocation has become a common in- teraction pattern in the documentation of web application programming interfaces (APIs). One of the earliest examples of this pattern being applied at scale is the Google APIs Ex- plorer. In this paper, we describe eight ways developers use such tools in software development, grounded in empirical analyses of the Google APIs Explorer. We then explain the utility of these tools by tying the use cases back to prior literature on programming. CCS Concepts · Software and its engineering → Inte- grated and visual development environments; Keywords Software Engineering, Human-Computer Inter- action, Documentation, Application Programming Interfaces 1 Introduction Web APIs are APIs invoked via HTTP. While there are a variety of forms these APIs can take (e.g., SOAP, JSON/REST, or gRPC), generally speaking they are a set of functions that are invoked with parameters, do some processing, and return a response. In a 2013 survey of 200 executives at companies with over $500 million in annual revenue, 77% of respondents rated web APIs as important "to determining the overall market position of companies in [their] sector over the next fve years" [4]. Since that time, business practices refect this sentiment; ProgrammableWeb reports that since 2014, nearly 2000 APIs have been added to their directory per year and in early 2017 the directory crossed the 17,000 mark [12]. APIs are a form of user interface; they connect a human (a developer) with a computer (the capabilities of a backend system). APIs are hard to use for a variety of reasons, includ- ing documentation, complex interrelationships between API components, inappropriate abstractions, and incongruence between coordinating APIs [13]. As user interfaces, princi- ples and methods from human-computer interaction can be applied to improve their usability, as Myers and Stylos have demonstrated in a variety of contexts [9]. Even if a developer manages to make an API work, there can be severe issues with the resulting code, such as major security holes [1]. PLATEAU’17 Workshop on Evaluation and Usability of Programming Lan- guages and Tools, October 23, 2017, Vancouver, CA Hou and Li identifed common patterns in online help requests surrounding the learning and use of APIs [3]. Two related paths towards solving these issues are the study of API structure and documentation. The space of API design de- cisions can be formalized [14]. And we can build knowledge on top of those formalizations; For example, the placement of a method within an API can have a profound impact on development speed [15]. However, not all usability problems are best solved through API design itself, but rather through documentation and tools. Robillard and Deline fnd that the "biggest hurdle when learn- ing an API is the documentation" [11]. A 2009 survey of soft- ware developers at Microsoft found that 78% of respondents claim to learn about an API by reading documentation, while 55% claim they used code examples [10]. In the same sur- vey, the author found that inadequate or missing resources provided the biggest obstacle to learning APIs. "If the docu- mentation for an API is good, it solves 99% of your problems" [11]. There is also a growing body of anecdotal evidence that API usability, heavily infuenced by the quality of the docu- mentation and learnability of the API, impacts adoption of an API. Myers and Stylos state that "usability can also afect API adoption; if an API takes too long for a programmer to learn, some organizations choose to use a diferent API or write simpler functionality from scratch" [9]. The Google APIs Explorer - hereafter referred to as Ex- plorer - is a tool that was developed to make it easier for developers to fnd and try out Google’s APIs before adopting them, without a signifcant time investment [6]. It can be em- bedded within API documentation or used standalone. There are numerous similar tools, including the Apigee API Con- sole and the Swagger UI. Over the past few years, these tools have quickly moved from being a novel technique to being a standard pattern applied in industry [8]. Generally speaking, the designs vary slightly, with these elements serving as the common thread: 1. For each API method, a graphical form that supports entering the request parameters and a submit button that executes the request. 2. Slightly more advanced widgets to support setting the appropriate form of authentication (e.g., OAuth), payloads, or headers.