Application Programming Interfaces Documentation Research Articles

Improving open data web API documentation through interactivity and natural language generation

Widely adoption of Information Technologies has resulted in the continuous growing of open data available on the Web. However, the lack of suitable mechanisms to understand open data sources hampers its reusability. One way to overcome this limitation is by means of Web Application Programming Interfaces (APIs) with proper documentation, nowadays being the existing very rudimentary, hard to follow, and sometimes incomplete or even inaccurate in most cases. In order to improve the documentation of Web APIs that access open data, this paper proposes a novel approach to automatically generate interactive Web API documentation, both machine and user readable. This process starts by analysing the documentation of an API to obtain important information, automatically constructing Natural Language descriptions of the main Web API concepts by applying Natural Language Processing (NLP), and specifically, language generation techniques. Then, the documentation is made interactive by making it available as a Web interface, offering easy access to open data provided by Web APIs. Therefore, the use and comprehension of the Web APIs is facilitated, thus promoting the reusability of open data. The feasibility of our approach is presented through a case study and an experiment with users, both showing the benefits of our approach.

A Case Study of Publishing Internal APIs to External Users

External service integration and adherence to industry standards has become ever more important for collections data management platforms. External APIs (Application Programming Interfaces), allow for the development of bi-directional data flows critical to service integration. In contrast to service-oriented backend APIs, public APIs must have continually up-to-date, comprehensive documentation that covers common use cases, on-the-fly request validation, and meaningful error messages. OpenAPI (OpenAPI Initiative 2021), a machine-readable API documentation specification can help significantly with testing and maintenance, and libraries can be used to automate common maintenance tasks. Specify 7 is a biological collections data management platform developed by the Specify Collections Consortium (Specify Software Consortium 2021). This presentation summarizes the challenges and lessons learned with publishing the existing backend Specify 7 API to a public-facing external API. Each Specify 7 API is composed of 200 resources. A standard set of CRUD (Create, Read, Update, Delete) operations is provided for each resource for client interaction with a group of service-based endpoints for bulk operations such as file uploads, file-based data imports, and attachment manipulation. To support the migration, we developed a custom library to enhance request validation. Parameter validation is extended through a real-time comparison against the existing schema and data. The library is available to the community under a MIT license on GitHub (https://github.com/specify/open_api_tools/). In this presentation, we will close with an overview of the next steps for the Specify 7 public API. These include: An update to the latest OpenAPI specification, version 3.1. The latest version aims to increase compatibility with the Javascript Object Notation (JSON) Schema specification, and thus would allow us to use JSON Schema (IETF Trust 2021) validation frameworks. An in-depth evaluation of GraphQL for its ability to force all endpoints to be strongly typed and automatic validation of request parameters and response objects. An update to the latest OpenAPI specification, version 3.1. The latest version aims to increase compatibility with the Javascript Object Notation (JSON) Schema specification, and thus would allow us to use JSON Schema (IETF Trust 2021) validation frameworks. An in-depth evaluation of GraphQL for its ability to force all endpoints to be strongly typed and automatic validation of request parameters and response objects.

Automatic Detection and Update Suggestion for Outdated API Names in Documentation

Application programming interfaces (APIs) continually evolve to meet ever-changing user needs, and documentation provides an authoritative reference for their usage. However, API documentation is commonly outdated because nearly all of the associated updates are performed manually. Such outdated documentation, especially with regard to API names, causes major software development issues. In this paper, we propose a method for automatically updating outdated API names in API documentation. Our insight is that API updates in documentation can be derived from API implementation changes between code revisions. To evaluate the proposed method, we applied it to four open source projects. Our evaluation results show that our method, FreshDoc, detects outdated API names in API documentation with 48 percent higher accuracy than the existing state-of-the-art methods do. Moreover, when we checked the updates suggested by FreshDoc against the developers' manual updates in the revised documentation, FreshDoc detected 82 percent of the outdated names. When we reported 40 outdated API names found by FreshDoc via issue tracking systems, developers accepted 75 percent of the suggestions. These evaluation results indicate that FreshDoc can be used as a practical method for the detection and updating of API names in the associated documentation.

A Theory of Robust API Knowledge

Creating modern software inevitably requires using application programming interfaces (APIs). While software developers can sometimes use APIs by simply copying and pasting code examples, a lack of robust knowledge of how an API works can lead to defects, complicate software maintenance, and limit what someone can express with an API. Prior work has uncovered the many ways that API documentation fails to be helpful, though rarely describes precisely why. We present a theory of robust API knowledge that attempts to explain why, arguing that effective understanding and use of APIs depends on three components of knowledge: (1) the domain concepts the API models along with terminology, (2) the usage patterns of APIs along with rationale, and (3) facts about an API’s execution to support reasoning about its runtime behavior. We derive five hypotheses from this theory and present a study to test them. Our study investigated the effect of having access to these components of knowledge, finding that while learners requested these three components of knowledge when they were not available, whether the knowledge helped the learner use or understand the API depended on the tasks and likely the relevance and quality of the specific information provided. The theory and our evidence in support of its claims have implications for what content API documentation, tutorials, and instruction should contain and the importance of giving the right information at the right time, as well as what information API tools should compute, and even how APIs should be designed. Future work is necessary to both further test and refine the theory, as well as exploit its ideas for better instructional design.

Automatic Detection and Repair Recommendation of Directive Defects in Java API Documentation

Application Programming Interfaces (APIs) represent key tools for software developers to build complex software systems. However, several studies have revealed that even major API providers tend to have incomplete or inconsistent API documentation. This can severely hamper the API comprehension and, as a consequence, the quality of the software built on them. In this paper, we propose DRONE (Detect and Repair of dOcumentatioN dEfects), a framework to automatically detect and repair defects from API documents by leveraging techniques from program analysis, natural language processing, and constraint solving. Specifically, we target at the directives of API documents, which are related to parameter constraints and exception handling declarations. Furthermore, in presence of defects, we also provide a prototypical repair recommendation system. We evaluate our approach on parts of the well-documented APIs of JDK 1.8 APIs (including javaFX) and Android 7.0 (level 24). Across the two empirical studies, our approach can detect API defects with an average F-measure of 79.9, 71.7, and 81.4 percent, respectively. The API repairing capability has also been evaluated on the generated recommendations in a further experiment. User judgments indicate that the constraint information is addressed correctly and concisely in the rendered directives.

How developers use API documentation

Application Programming Interfaces (APIs) play a crucial role in modern software engineering. However, learning to use a new API often is a challenge for developers. In order to support the learning process effectively, we need to understand how developers use documentation when starting to work with a new API. We report an exploratory study that observed developers while they solved programming tasks involving a simple API. The results reveal differences regarding developer activities and documentation usage that a successful design strategy for API documentation needs to accommodate. Several guidelines to optimize API documentation are discussed.

Enriching API Documentation with Code Samples and Usage Scenarios from Crowd Knowledge

As one key resource to learn Application Programming Interfaces (APIs), a lot of API reference documentation lacks code samples with usage scenarios, thus heavily hindering developers from programming with APIs. Although researchers have investigated how to enrich API documentation with code samples from general code search engines, two main challenges remain to be resolved, including the quality challenge of acquiring high-quality code samples and the mapping challenge of matching code samples to usage scenarios. In this study, we propose a novel approach named ADECK towards enriching API documentation with code samples and corresponding usage scenarios by leveraging crowd knowledge from Stack Overflow, a popular technical Question and Answer (Q&A) website attracting millions of developers. Given an API related Q&A pair, a code sample in the answer is extensively evaluated by developers and targeted towards resolving the question under the specified usage scenario. Hence, ADECK can obtain high-quality code samples and map them to corresponding usage scenarios to address the above challenges. Extensive experiments on the Java SE and Android API documentation show that the number of code-sample-illustrated API types in the ADECK-enriched API documentation is 3.35 and 5.76 times as many as that in the raw API documentation. Meanwhile, the quality of code samples obtained by ADECK is better than that of code samples by the baseline approach eXoaDocs in terms of correctness, conciseness, and usability, e.g., the average correctness values of representative code samples obtained by ADECK and eXoaDocs are 4.26 and 3.28 on a 5-point scale in the enriched Java SE API documentation. In addition, an empirical study investigating the impacts of different types of API documentation on the productivity of developers shows that, compared against the raw and the eXoaDocs-enriched API documentation, the ADECK-enriched API documentation can help developers complete 23.81 and 14.29 percent more programming tasks and reduce the average completion time by 9.43 and 11.03 percent.

To Do or Not To Do: Distill crowdsourced negative caveats to augment api documentation

Negative caveats of application programming interfaces (APIs) are about “how not to use an API,” which are often absent from the official API documentation. When these caveats are overlooked, programming errors may emerge from misusing APIs, leading to heavy discussions on Q&A websites like Stack Overflow. If the overlooked caveats could be mined from these discussions, they would be beneficial for programmers to avoid misuse of APIs. However, it is challenging because the discussions are informal, redundant, and diverse. For this, for example, we propose Disca, a novel approach for automatically Distilling desirable API negative caveats from unstructured Q&A discussions. Through sentence selection and prominent term clustering, Disca ensures that distilled caveats are context‐independent, prominent, semantically diverse, and nonredundant. Quantitative evaluation in our experiments shows that the proposed Disca significantly outperforms four text‐summarization techniques. We also show that the distilled API negative caveats could greatly augment API documentation through qualitative analysis.

Improving access to API documentation for developers with Docs‐as‐Code‐as‐a‐service

ABSTRACTWeb Application Programming Interfaces (APIs) provide the connective tissue that developers need to integrate Internet services and create “software‐as‐a‐service” (SaaS) applications. To learn an API's usage, developers often turn to their web browsers to access documentation and try out APIs. However, traditional approaches to documentation present obstacles that can hamper API comprehension and developer productivity. To overcome these obstacles, practitioners are adopting a new approach called Docs‐as‐Code, in which documents are published with many of the same tools and practices used to deploy source code. In this paper, we present Dev Center, a system based in part on the Docs‐as‐Code framework and designed to provide ubiquitous access to a broad set of API documentation resources. Preliminary findings suggest that Dev Center could potentially improve API comprehension and developer productivity, while Docs‐as‐Code could benefit related research efforts.

API library-based identification and documentation of usage patterns

Application programming interfaces (APIs) are important sources for supporting source code reuse as each API provides a large set of pre-implemented functionalities that support programmers to achieve their daily work in different contexts. However, APIs provide huge number of classes and methods that hinder programmers to understand and use APIs. Numerous client-based approaches have been proposed for facilitating APIs usage through identifying frequent usage pattern. Although they represent significant efforts for helping APIs understanding, the client applications are not available for either newly released APIs libraries or APIs that are not widely used. In this paper, a non-client-based approach for frequent usage patterns identification and documentation is proposed. The approach incorporates hierarchical clustering algorithm and API's source code information. An experimental evaluation is conducted using four widely used APIs. For all studied APIs, the results show that the proposed approach is comparable with client-based approaches in terms of usage patterns cohesion.

API library-based identification and documentation of usage patterns

Application programming interfaces (APIs) are important sources for supporting source code reuse as each API provides a large set of pre-implemented functionalities that support programmers to achieve their daily work in different contexts. However, APIs provide huge number of classes and methods that hinder programmers to understand and use APIs. Numerous client-based approaches have been proposed for facilitating APIs usage through identifying frequent usage pattern. Although they represent significant efforts for helping APIs understanding, the client applications are not available for either newly released APIs libraries or APIs that are not widely used. In this paper, a non-client-based approach for frequent usage patterns identification and documentation is proposed. The approach incorporates hierarchical clustering algorithm and API's source code information. An experimental evaluation is conducted using four widely used APIs. For all studied APIs, the results show that the proposed approach is comparable with client-based approaches in terms of usage patterns cohesion.

TMAP: Discovering relevant API methods through text mining of API documentation

AbstractDevelopers often migrate their applications to support various platform/programming‐language application programming interfaces (APIs) to retain existing users and to attract new users. To migrate an application written using 1 API (source) to another API (target), a developer must know how the methods in the source API map to the methods in the target API. Given that a typical platform or language exposes a large number of API methods, manually discovering API mappings is prohibitively resource‐intensive and may be error prone. The goal of this research is to support software developers in migrating an application from a source API to a target API by automatically discovering relevant method mappings across APIs using text mining on the natural language API method descriptions. This paper proposes text mining based approach (TMAP) to discover relevant API mappings. To evaluate our approach, we used TMAP to discover API mappings for 15 classes across (1) Java and C# API; and (2) Java ME and Android API. We compared the discovered mappings with state‐of‐the‐art source code analysis‐based approaches: Rosetta and StaMiner. Our results indicate that TMAP on average found relevant mappings for 56% and 57% more methods compared to the Rosetta and the StaMiner approaches, respectively.

Patterns of Knowledge in API Reference Documentation

Reading reference documentation is an important part of programming with application programming interfaces (APIs). Reference documentation complements the API by providing information not obvious from the API syntax. To improve the quality of reference documentation and the efficiency with which the relevant information it contains can be accessed, we must first understand its content. We report on a study of the nature and organization of knowledge contained in the reference documentation of the hundreds of APIs provided as a part of two major technology platforms: Java SDK 6 and .NET 4.0. Our study involved the development of a taxonomy of knowledge types based on grounded methods and independent empirical validation. Seventeen trained coders used the taxonomy to rate a total of 5,574 randomly sampled documentation units to assess the knowledge they contain. Our results provide a comprehensive perspective on the patterns of knowledge in API documentation: observations about the types of knowledge it contains and how this knowledge is distributed throughout the documentation. The taxonomy and patterns of knowledge we present in this paper can be used to help practitioners evaluate the content of their API documentation, better organize their documentation, and limit the amount of low-value content. They also provide a vocabulary that can help structure and facilitate discussions about the content of APIs.

What should developers be aware of? An empirical study on the directives of API documentation

Application Programming Interfaces (API) are exposed to developers in order to reuse software libraries. API directives are natural-language statements in API documentation that make developers aware of constraints and guidelines related to the usage of an API. This paper presents the design and the results of an empirical study on the directives of API documentation of object-oriented libraries. Its main contribution is to propose and extensively discuss a taxonomy of 23 kinds of API directives.

Comparing and evaluating terminology services application programming interfaces: RxNav, UMLSKS and LexBIG

To facilitate the integration of terminologies into applications, various terminology services application programming interfaces (API) have been developed in the recent past. In this study, three publicly available terminology services API, RxNav, UMLSKS and LexBIG, are compared and functionally evaluated with respect to the retrieval of information from one biomedical terminology, RxNorm, to which all three services provide access. A list of queries is established covering a wide spectrum of terminology services functionalities such as finding RxNorm concepts by their name, or navigating different types of relationships. Test data were generated from the RxNorm dataset to evaluate the implementation of the functionalities in the three API. The results revealed issues with various aspects of the API implementation (eg, handling of obsolete terms by LexBIG) and documentation (eg, navigational paths used in RxNav) that were subsequently addressed by the development teams of the three API investigated. Knowledge about such discrepancies helps inform the choice of an API for a given use case.

Studying the Documentation of an API for Enterprise Service-Oriented Architecture

All software today is written using application programming interfaces (APIs). We performed a user study of the online documentation of a large and complex API for Enterprise Service-Oriented Architecture (eSOA), which identified many issues and recommendations for making API documentation easier to use. eSOA is an appropriate testbed because the target users include high-level business experts who do not have significant programming expertise and thus can be classified as “end-user developers.” Our study showed that the participants’ background influenced how they navigated the documentation. Lack of familiarity with business terminology was a barrier for developers without business application experience. Both groups avoided areas of the documentation that had an inconsistent visual design. A new design for the documentation that supports flexible navigation strategies seems to be required to support the wide range of users for eSOA. This paper summarizes our study and provides recommendations for future documentation for APIs.