API Documentation Research Articles

RESTBERTa: a Transformer-based question answering approach for semantic search in Web API documentation

To enable machines to process state-of-practice Web API documentation, we propose a Transformer model for the generic task of identifying a Web API element within a syntax structure that matches a natural language query. We solve this semantic-search task with Transformer-based question answering and demonstrate the applicability of our approach to two different tasks, namely the discovery of endpoints and the identification of parameters in payload schemas. With samples from 2321 OpenAPI documentation, we prepare different datasets and fine-tune pre-trained BERT models to these two tasks. We evaluate the generalizability and the robustness of our fine-tuned models. We achieve accuracies of 81.95% for the parameter-matching and 88.44% for the endpoint-discovery task.

TCCCD: Triplet-Based Cross-Language Code Clone Detection

Code cloning is a common practice in software development, where developers reuse existing code to accelerate programming speed and enhance work efficiency. Existing clone-detection methods mainly focus on code clones within a single programming language. To address the challenge of code clone instances in cross-platform development, we propose a novel method called TCCCD, which stands for Triplet-Based Cross-Language Code Clone Detection. Our approach is based on machine learning and can accurately detect code clone instances between different programming languages. We used the pre-trained model UniXcoder to map programs written in different languages into the same vector space and learn their code representations. Then, we fine-tuned TCCCD using triplet learning to improve its effectiveness in cross-language clone detection. To assess the effectiveness of our proposed approach, we conducted thorough comparative experiments using the dataset provided by the paper titled CLCDSA (Cross Language Code Clone Detection using Syntactical Features and API Documentation). The experimental results demonstrated a significant improvement of our approach over the state-of-the-art baselines, with precision, recall, and F1-measure scores of 0.96, 0.91, and 0.93, respectively. In summary, we propose a novel cross-language code-clone-detection method called TCCCD. TCCCD leverages the pre-trained model UniXcode for source code representation and fine-tunes the model using triplet learning. In the experimental results, TCCCD outperformed the state-of-the-art baselines in terms of the precision, recall, and F1-measure.

Phenopacket-tools: Building and validating GA4GH Phenopackets.

The Global Alliance for Genomics and Health (GA4GH) is a standards-setting organization that is developing a suite of coordinated standards for genomics. The GA4GH Phenopacket Schema is a standard for sharing disease and phenotype information that characterizes an individual person or biosample. The Phenopacket Schema is flexible and can represent clinical data for any kind of human disease including rare disease, complex disease, and cancer. It also allows consortia or databases to apply additional constraints to ensure uniform data collection for specific goals. We present phenopacket-tools, an open-source Java library and command-line application for construction, conversion, and validation of phenopackets. Phenopacket-tools simplifies construction of phenopackets by providing concise builders, programmatic shortcuts, and predefined building blocks (ontology classes) for concepts such as anatomical organs, age of onset, biospecimen type, and clinical modifiers. Phenopacket-tools can be used to validate the syntax and semantics of phenopackets as well as to assess adherence to additional user-defined requirements. The documentation includes examples showing how to use the Java library and the command-line tool to create and validate phenopackets. We demonstrate how to create, convert, and validate phenopackets using the library or the command-line application. Source code, API documentation, comprehensive user guide and a tutorial can be found at https://github.com/phenopackets/phenopacket-tools. The library can be installed from the public Maven Central artifact repository and the application is available as a standalone archive. The phenopacket-tools library helps developers implement and standardize the collection and exchange of phenotypic and other clinical data for use in phenotype-driven genomic diagnostics, translational research, and precision medicine applications.

Slowing Down the Aging of Learning-Based Malware Detectors With API Knowledge

Learning-based malware detectors are widely used in practice to safeguard real-world computers. One major challenge is known as model aging, where the effectiveness of these models drops drastically as malware variants keep evolving. To tackle model aging, most existing works choose to label new samples to retrain the aged models. However, such data-perspective methods often require excessive costs in labeling and retraining. In this article, we observe that during evolution, malware samples often preserve similar malicious semantics while switching to new implementations with semantically equivalent APIs. Such observation enables us to look into the problem from a different perspective: feature space. More specifically, if the models can capture the intrinsic semantics of malware variants from feature space, it will help slow down the aging of learning-based detectors. Based on this insight, we design <sc xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:xlink="http://www.w3.org/1999/xlink">APIGraph</small> to automatically extract API knowledge from API documentation and incorporate these knowledge into the training of malware detection models. We use <sc xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:xlink="http://www.w3.org/1999/xlink">APIGraph</small> to enhance 5 state-of-the-art malware detectors, covering both Android and Windows platforms and various learning algorithms. Experiments on large-scale, evolutionary datasets with nearly 340K samples show that <sc xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:xlink="http://www.w3.org/1999/xlink">APIGraph</small> can help slow down the aging of these models by 5.9% to 19.6%, as well as reduce labeling efforts from 33.07% to 96.30% on top of data-perspective methods.

Building Enterprise-Wide API-First Strategy for Medium to Large Organizations

In this paper, we provided a comprehensive guide on implementing an API-first approach within medium to large organizations. The basic framework starts by defining APIs and their role in modern business systems, using an example of two companies sharing order-related information through APIs. We covered the concept of API-first as a design philosophy, the growth of API usage, and the complexities faced by medium to large organizations in API adoption. The paper also discusses different integration patterns, the importance of understanding API and integration strategies, and the key elements for a successful API-first integration strategy. Additionally, it emphasizes the role of API gateways, the need for standardized API documentation, and the avoidance of excessive reuse of APIs. The document highlighted the importance of measuring API success using business KPIs. The paper concludes with the real-life example of the large organization with complex ERP and data systems and how the guidelines provided in the paper can help abstract the complexities with the help of API-First approach, finally the paper covered the security and data consistency as an important factor in defining the strategy.

APIRO: A Framework for Automated Security Tools API Recommendation

Security Orchestration, Automation, and Response (SOAR) platforms integrate and orchestrate a wide variety of security tools to accelerate the operational activities of Security Operation Center (SOC). Integration of security tools in a SOAR platform is mostly done manually using APIs, plugins, and scripts. SOC teams need to navigate through API calls of different security tools to find a suitable API to define or update an incident response action. Analyzing various types of API documentation with diverse API format and presentation structure involves significant challenges such as data availability, data heterogeneity, and semantic variation for automatic identification of security tool APIs specific to a particular task. Given these challenges can have negative impact on SOC team’s ability to handle security incident effectively and efficiently, we consider it important to devise suitable automated support solutions to address these challenges. We propose a novel learning-based framework for automated security tool API R ecommendation for security O rchestration, automation, and response, APIRO . To mitigate data availability constraint, APIRO enriches security tool API description by applying a wide variety of data augmentation techniques. To learn data heterogeneity of the security tools and semantic variation in API descriptions, APIRO consists of an API-specific word embedding model and a Convolutional Neural Network (CNN) model that are used for prediction of top three relevant APIs for a task. We experimentally demonstrate the effectiveness of APIRO in recommending APIs for different tasks using three security tools and 36 augmentation techniques. Our experimental results demonstrate the feasibility of APIRO for achieving 91.9% Top-1 Accuracy. Compared to the state-of-the-art baseline, APIRO is 26.93%, 23.03%, and 20.87% improved in terms of Top-1, Top-2, and Top-3 Accuracy and outperforms the baseline by 23.7% in terms of Mean Reciprocal Rank (MRR).

API Testing Using Postman Tool

Abstract: Postman is one of the greatest API automation and documentation tools available today. Postman began as a simple Chrome browser plugin and has now grown to be a full API testing solution used by 5 million developers and over 100,000 enterprises all over the world. With a $2 billion value, it's a unicorn in its own right, and it's become the go-to platform for creating enterprise APIs. As the API economy continues to growing, more challenges are created for developers. The old methods of manually creating and testing APIs no longtime scale as today’s software and services can interface with hundreds of APIs within a single application. Development, testing, and delivery teams must work together to make sure that applications work barrier with APIs to provide a business advantage, rather than cause a business obstacle. Collaboration and operational efficiency are the keys to sharing modern API- powered applications. And this is the space that Postman plays in. In one of our GlobalLogic projects related to a Banking as well as Financial Services Customer Communications Management platform that is CCMP, we need to use Postman and its CI/CD add-on Newman to create, customize and automate Web API tests. This white paper and technical report narrate our passage direct this automation and showcases some learnings and best practices realized along the way. This is our view from the trenches on the capacity and possibilities of the Postman platform for API testing

OpenAPI framework for the Web of Things

The Web of Things (WoT) Architecture recommendation of W3C defines a framework for integrating Things (e.g. devices) into the Web. It establishes an information representation of Things based on JSON-LD and RESTful API interfaces to enable access to Things. Leveraging the latest results on hypermedia construction and documentation of RESTful APIs, we argue that OpenAPI can also be used to provide documentation of Things that adheres to the W3C Architecture recommendation. OpenAPI is a widely accepted industry standard endorsed by prominent industry vendors and user communities. Therefore, it is mature and can become acceptable. An essential part of the approach is a mechanism that facilitates the generation of OpenAPI Thing Descriptions and a Web proxy that implements access to Things on the Web. An implementation of the API is also proposed and evaluated. Last but not least, OpenAPI achieves uniformity of representation of both types of WoT entities (i.e. Web services and Things) that co-exist and interact with each other in an application. This has a positive impact on the way WoT applications are designed and implemented.

English for Scientific &amp; Technical Writing

Abstract: ‘Communication is important not only in an organization but also in our daily life. When we use communication pertaining to technical, industrial or business matters belong to the category of technical or business communication’’. Scientific and technical writing, a form of technical communication, is a style of writing used in fields of diverse as computer hardware and software, engineering, chemistry, the aerospace, industry, robotics, finance, consumer electronics and biotechnology. Technical writing teams or departments are often referred to as Information development, User Assistance, Technical Documentation, or Technical Publications. Technical writers themselves may be called API writers, information developers, documentation specialists, documentation engineers, or technical content developers. Specific areas to be elaborated on the full paper. “ Nature of scientific and technical documentation-basics of scientific and technical documentation- organization in technical and scientific documentation – style in technical and scientific documentation –ABC of good technical and scientific documentation – history of technical and scientific documentation’. Broadly speaking, technical documentation can be categorized into three types, depending on the style of writing, the level of knowledge transferred and the target audience. End user assistance: These information products help a user understand how ton use a technical software or hardware product. Traditional technical documentation: here the objective of the writer is to communicate with a specific audience.

Update 2.0 to “ViroCon: A software to compute multivariate extremes using the environmental contour method”

Update 2.0 to “ViroCon: A software to compute multivariate extremes using the environmental contour method”

“I just looked for the solution!”On Integrating Security-Relevant Information in Non-Security API Documentation to Support Secure Coding Practices

Software developers build complex systems using plenty of third-party libraries. Documentation is key to understand and use the functionality provided via the libraries’ APIs. Therefore, functionality is the main focus of contemporary API documentation, while cross-cutting concerns such as security are almost never considered at all, especially when the API itself does not provide security features. Documentations of JavaScript libraries for use in web applications, e.g., do not specify how to add or adapt a Content Security Policy (CSP) to mitigate content injection attacks like Cross-Site Scripting (XSS). This is unfortunate, as security-relevant API documentation might have an influence on secure coding practices and prevailing major vulnerabilities such as XSS. For the first time, we study the effects of integrating security-relevant information in non-security API documentation. For this purpose, we took CSP as an exemplary study object and extended the official Google Maps JavaScript API documentation with security-relevant CSP information in three distinct manners. Then, we evaluated the usage of these variations in a between-group eye-tracking lab study involving N=49 participants. Our observations suggest: (1) Developers are focused on elements with code examples. They mostly skim the documentation while searching for a quick solution to their programming task. This finding gives further evidence to results of related studies. (2) The location where CSP-related code examples are placed in non-security API documentation significantly impacts the time it takes to find this security-relevant information. In particular, the study results showed that the proximity to functional-related code examples in documentation is a decisive factor. (3) Examples significantly help to produce secure CSP solutions. (4) Developers have additional information needs that our approach cannot meet. Overall, our study contributes to a first understanding of the impact of security-relevant information in non-security API documentation on CSP implementation. Although further research is required, our findings emphasize that API producers should take responsibility for adequately documenting security aspects and thus supporting the sensibility and training of developers to implement secure systems. This responsibility also holds in seemingly non-security relevant contexts.

The inconsistency of documentation: a study of online C standard library documents

The C standard libraries are basic function libraries standardized by the C language. Programmers usually refer to their API documentation provided by third-party websites. Unfortunately, these documents are not necessarily complete or accurate, especially for constraint sentences of API usage, which are called Security Specifications (SSs). SS issues can prevent programmers from following obligatory constraints, which results in API misuse vulnerabilities. Previous work studying SS issues could only find certain types of inaccurate SSs through checking the compliance between API usage and existing SSs. Therefore, we propose a novel approach SSeeker for quickly discovering missing and inaccurate SSs through the inconsistency of semantically similar SSs. More specifically, SSeeker first completes broken sentences and discovers SSs from them by judging their constraint sentiment. Then SSeeker puts semantically similar SSs from different sources into a group, which can be used to discover missing or inaccurate SSs. With the help of SSeeker, we investigated 4 popular online third-party C standard library documents, studied their conformity with the C99 standard, analyzed their APIs and SSs, and discovered 92 prototype issues, 15 web page issues, and 96 SS issues.

MINE 2.0: enhanced biochemical coverage for peak identification in untargeted metabolomics.

Although advances in untargeted metabolomics have made it possible to gather data on thousands of cellular metabolites in parallel, identification of novel metabolites from these datasets remains challenging. To address this need, Metabolic in silico Network Expansions (MINEs) were developed. A MINE is an expansion of known biochemistry which can be used as a list of potential structures for unannotated metabolomics peaks. Here, we present MINE 2.0, which utilizes a new set of biochemical transformation rules that covers 93% of MetaCyc reactions (compared to 25% in MINE 1.0). This results in a 17-fold increase in database size and a 40% increase in MINE database compounds matching unannotated peaks from an untargeted metabolomics dataset. MINE 2.0 is thus a significant improvement to this community resource. The MINE 2.0 website can be accessed at https://minedatabase.ci.northwestern.edu. The MINE 2.0 web API documentation can be accessed at https://mine-api.readthedocs.io/en/latest/. The data and code underlying this article are available in the MINE-2.0-Paper repository at https://github.com/tyo-nu/MINE-2.0-Paper. MINE 2.0 source code can be accessed at https://github.com/tyo-nu/MINE-Database (MINE construction), https://github.com/tyo-nu/MINE-Server (backend web API) and https://github.com/tyo-nu/MINE-app (web app). Supplementary data are available at Bioinformatics online.

A semantic main path analysis method to identify multiple developmental trajectories

• A semantic main path analysis approach is put forward to identify simultaneously multiple developmental trajectories in a target field. • To improve topical coherence of documents along a same trajectory, the conventional link weights are armed with the semantic information based ones. • After all paths are enumerated effectively with a dynamic programming based search algorithm, a density-based clustering method is used to divide them into several groups. • The source codes in Python language can be freely accessed at the GitHub and PyPi with detailed API documentation, thus to promote the related studies. Main Path Analysis (MPA) is widely used to trace the developmental trajectory of a technological field through a citation network. The citation-based traversal weight is usually utilized to cherry-pick the most significant path. However, the theme of documents along a main path may not be so coherent, and it is very possible to miss the main paths of significant sub-fields overall in a domain. Furthermore, the global path search algorithm in conventional MPA also suffers from high space complexity due to the exhaustive strategy. To address these limitations, a new method, named as semantic MPA (sMPA), is proposed by leveraging semantic information in two steps of candidate path generation and main path selection. In the meanwhile, the resulting source code can be freely accessed. To demonstrate the advantages of our method, extensive experiments are conducted on a patent dataset pertaining to lithium-ion battery in electric vehicle. Experimental results show that our sMPA is capable of discovering more knowledge flows from important sub-fields, and improving the topical coherence of candidate paths as well.

Understanding Roxygen package documentation in R

R is a package-based programming ecosystem that provides an easy way to install third-party code, datasets, and examples. Thus, R developers rely heavily on the documentation of the packages they import to use them correctly and accurately. This documentation is often written using Roxygen, equivalent to Java’s well-known Javadoc. This two-part study provides the first analysis in this area. First, 379 systematically-selected, open-source R packages were mined and analysed to address the quality of their documentation in terms of presence, distribution, and completeness to identify potential sources of documentation debt of technical debt that describes problems in the documentation. Second, a survey addressed how R package developers perceive documentation and face its challenges (with a response rate of 10.04%). Results show that incomplete documentation is the most common smell, with several cases of incorrect use of the Roxygen utilities. Unlike in traditional API documentation, developers do not focus on how behaviour is implemented but on common use cases and parameter documentation. Respondents considered the examples section the most useful, and commonly perceived challenges were unexplained examples, ambiguity, incompleteness and fragmented information.

Documentation Matters: Human-Centered AI System to Assist Data Science Code Documentation in Computational Notebooks

Computational notebooks allow data scientists to express their ideas through a combination of code and documentation. However, data scientists often pay attention only to the code, and neglect creating or updating their documentation during quick iterations. Inspired by human documentation practices learned from 80 highly-voted Kaggle notebooks, we design and implement Themisto, an automated documentation generation system to explore how human-centered AI systems can support human data scientists in the machine learning code documentation scenario. Themisto facilitates the creation of documentation via three approaches: a deep-learning-based approach to generate documentation for source code, a query-based approach to retrieve online API documentation for source code, and a user prompt approach to nudge users to write documentation. We evaluated Themisto in a within-subjects experiment with 24 data science practitioners, and found that automated documentation generation techniques reduced the time for writing documentation, reminded participants to document code they would have ignored, and improved participants’ satisfaction with their computational notebook.

Elicitation of functional requirements from the application programming interface documentation for functional testing

We address a common problem in this paper. The only available documentation for a computer program consists of a user API documentation while we need to identify functional requirements and build test suite to test them. We describe a technique for functional requirements elicitation from the user API documentation. Requirements management tool Requality is exploited in this technique. The tool has been used in several industrial software verification projects.

Applying Model-Driven Engineering to Stimulate the Adoption of DevOps Processes in Small and Medium-Sized Development Organizations

Microservice architecture (MSA) denotes an increasingly popular architectural style in which business capabilities are wrapped into autonomously developable and deployable software components called microservices. Microservice applications are developed by multiple DevOps teams each owning one or more services. In this article, we explore the state of how DevOps teams in small and medium-sized organizations (SMOs) cope with MSA and how they can be supported. We show through a secondary analysis of an exploratory interview study comprising six cases, that the organizational and technological complexity resulting from MSA poses particular challenges for small and medium-sized organizations (SMOs). We apply model-driven engineering to address these challenges. As results of the second analysis, we identify the challenge areas of building and maintaining a common architectural understanding, and dealing with deployment technologies. To support DevOps teams of SMOs in coping with these challenges, we present a model-driven workflow based on LEMMA—the Language Ecosystem for Modeling Microservice Architecture. To implement the workflow, we extend LEMMA with the functionality to (i) generate models from API documentation; (ii) reference remote models owned by other teams; (iii) generate deployment specifications; and (iv) generate a visual representation of the overall architecture. We validate the model-driven workflow and our extensions to LEMMA through a case study showing that the added functionality to LEMMA can bring efficiency gains for DevOps teams. To develop best practices for applying our workflow to maximize efficiency in SMOs, we plan to conduct more empirical research in the field in the future.

QA4GIS: A novel approach learning to answer GIS developer questions with API documentation

AbstractCommunity‐based question answering websites have attracted more and more scholars and developers to discuss domain knowledge and software development. In this article, we focus on the GIS section of the Stack Exchange website and develop a novel approach, QA4GIS, a deep learning‐based system for question answering tasks with a deep neural network (DNN) model to extract the representation of the query–API document pair. We use the LambdaMART model to rerank the candidate API documents. We begin with an empirical analysis of the questions and answers, demonstrating that API documents could answer 52.93% of the questions. Then we evaluate QA4GIS by comparing it with 10 other baselines. The experiment results show that QA4GIS can improve 21.39% on the MAP score and 22.34% on the MRR score compared with the best baseline SIF.

РАЗРАБОТКА КРАУДСОРСИНГОВОГО ИНТЕРНЕТ-ПОРТАЛА ДЛЯ ОБНАРУЖЕНИЯ И КОНТРОЛЯ ЧИСЛЕННОСТИ РЕДКИХ И ИСЧЕЗАЮЩИХ ВИДОВ РАСТЕНИЙ В УРБОЭКОСИСТЕМЕ НА ПРИМЕРЕ Г. КУРСКА

Currently, at least 10% of plant species and even more animals are threatened with extinction on the planet Earth. The rate of extinction of species is 50-100 times higher than the natural rate. This trend has continued over the past 20-25 years. There are 439 endangered species in the Kursk region. Of these, 160 species of fauna, 265 species of plants and 14 species of fungi. The problem of conservation of rare and endangered plant species can be solved by their timely detection, subsequent monitoring and protection in specific habitats. Based on this, the purpose of this study is to develop tools for creating the most complete databases of rare and endangered plant species in urban ecosystems based on crowdsourcing methods and modern information technologies. At the initial stage of the implementation of projects for the conservation of biodiversity, the main difficulty lies in the mass identification of the presence of plant and animal species that are subject to protection on the territory of the city. It is possible to solve this problem using crowdsourcing methods. The team of the Southwestern State University has developed an Environmental crowdsourcing portal of the Kursk Region. This portal is designed on a modular basis, it includes various modules, including a module designed to solve the problem of biodiversity conservation. The module is developed using HTML5, CSS3, JavaScript, PHP and functions in user and administrator modes. Additionally, the functional blocks of thematic databases are designed using MySQL. Based on the database tables and the Yandex Maps API documentation, blocks for loading and displaying information on an interactive map have been developed. The module ensures the involvement of a wide range of urban population to identify the presence of plant and animal species that are subject to protection on the territory of the city. The module of the Environmental Crowdsourcing Portal of the Kursk Region considered in the article provides not only a solution to the problem of filling the database of rare and endangered species of plants and animals, but, like all crowdsourcing environmental projects, contributes to improving the level of environmental education of citizens, forming their consciousness and active life position.