Some structural measures of API usability

Abstract

In this age of collaborative software development, the importance of usable APIs is well recognized. There already exists a rich body of literature that addresses issues ranging from how to design usable APIs to assessing qualitatively the usability of a given API. However, there does not yet exist a set of generalpurpose metrics that can be pressed into service for a more quantitative assessment of API usability. The goal of this paper is to remedy this shortcoming in the literature. Our work presents a set of formulas that examine the API method declarations from the perspective of several commonly held beliefs regarding what makes APIs difficult to use. We validate the numerical characterizations of API usability as produced by our metrics through the APIs of several software systems. SOME STRUCTURAL MEASURES OF API USABILITY 77 specified it to be in the published API document, without any judgment regarding what functionality the API offers vis-a-vis the functionality it ought to offer. More specifically, an API of a module is a set of method declarations that an API designer has chosen to list in the API document for that module. In other words, we will only look at the usability of the structure of the API. ¶ Note that we do not attempt to answer the question of whether an API is truly representing the functionality that it is supposed to. Testing an API for what functionality it represents vis-a-vis the capabilities of the module is obviously a very important problem in its own right and orthogonal to the issue of the usability. As the reader will see in what follows, even if an API were to be perfect with regard to the functionality represented by it, it may not be easy to use because of various structural defects.The next section highlights some of the important structural issues that can make it difficult for a client to use an API. Subsequently, we will take up the more significant of these issues and present metrics that measure the usability of an API with respect to those issues. SOME COMMONLY HELD BELIEFS ABOUT WHAT CONSTITUTE DEFECTS IN API METHOD DECLARATIONSWhen the method declarations in an API document possess one or more of the following features, they are generally considered to be a source of frustration for the programmers: S1: Methods with similar names returning different types of valuesIn OO software systems, overloaded methods of the same name but having different return types can be frustrating to the programmers. The problems created by this structural issue have been well discussed in user forums. For instance, see the blog by Abrams [5]:When the overloaded methods return different types, the programmer must remember the associations between the return types and the method signatures for the different overloadings. For example, consider the following two methods defined for the class javax.naming.directory.Attribute in Java 5:The first method add() assumes that there exists an ordered list of attribute values; this method inserts the attribute value supplied through the second argum...

Automated measurement of API usability: The API Concepts Framework

“…the task to be solved, as well as the developer's experience), and (2) that both the API and the resulting code are evaluated. Existing API usability metrics [11,13] only evaluate the API itself, but not the resulting code, and ignore the context of use. There are only very few mentions of similar ideas: [21] defines interface complexity as a combination of the complexities of the interface signature, constraints and configuration, where signature conforms to our definition interface complexity, and configuration to setup complexity.…”

“…A different approach is taken in [13], where a set of 9 metrics is introduced that are based on existing API design guidelines. The metrics are easy to apply and relate very well to the respective guidelines.…”

Improving API usability

“…One example of applying this guideline is that the order of parameters should be the same in every method. However, javax.xml.stream.XMLStreamWriter for Java 8 has different overloadings for the writeStartElement method, which take the String parameters localName and namespaceURI in the opposite order from each other [18], and since they are both strings, the compiler will not be able to detect any user errors: Another Nielsen guideline is to reduce error proneness [16]. This can apply to avoiding long sequences of parameters of the same type, which the API user is likely to get wrong, and the compiler will also not be able to check.…”

“…This can apply to avoiding long sequences of parameters of the same type, which the API user is likely to get wrong, and the compiler will also not be able to check. For example, the class TPASupplierOrderXDE in Petstore (J2EE demonstration software from Oracle) takes a sequence of nine Strings [18]: Similarly, in Microsoft's .Net, System.Net.Cookie has 4 constructors, that take 0, 2, 3, or 4 strings as input. Another application of this principle is to make the default or example parameters do the right thing.…”

“…For example, one tool can evaluate APIs against a set of nine metrics including looking for: method overloaded but with different return types, too many parameters in a row with the same types, and consistency of parameter orderings across different methods [18]. Similarly, the API Concepts Framework takes the context of use into account because it evaluates both the API and samples of code using the API [20].…”