We present the implementation of the smartAPI ecosystem to facilitate the creation of FAIR (Findable, Accessible, Interoperable, Reusable) APIs. The emergence of “big data” has accelerated the growth of API space, and hence an excellent opportunity has now arisen to build an intelligent network of Web APIs that empowers a given application to automatically discover and link suitable APIs. However, even semantically relevant APIs are documented independently and isolated from other APIs, and the API descriptions are minimally shared and reused [1]. smartAPI fills this gap by creating API descriptions that are accessible and reusable, and annotating them with explicit knowledge about the structure and datatypes of the API parameters and responses in order to achieve more findable and interoperable APIs. In our previous work [3], we identified the metadata elements that are crucial to the description of Web APIs and subsequently developed the smartAPI metadata specification available at https://websmartapi.github.io/smartapi_specification using the FAIR principles (Findable, Accessible, Interoperable, Reusable) [2]. In this paper, we present the implementation of the smartAPI ecosystem. We provided a comprehensive review of the challenges related to the existing systems in API life-cycle management in [3]. The Swagger editor12 has the largest and most active community among API editors. It uses the OpenAPI specification13, which defines a standard, language-agnostic interface to HTTP APIs in JSON format. Swagger's auto-completion functionality suggests predefined metadata; however, it does not offer a means to reuse/share annotations from/with other API documents.
? Corresponding authors 12 https://swagger.io/swagger-editor/ 13 https://github.com/OAI/OpenAPI-Specification
In contrast, smartAPI not only enables authoring and annotating API documents, but also contributes towards improved visibility, interoperability, and reusability of Web APIs. Rather than building an API editor from scratch, we extended the Swagger editor to fulfill the smartAPI objectives (Section 2).
14 http://smart-api.info/registry/ 15 http://smart-api.info/api/metadata/all smartAPI ecosystem Swagger editor, by suggesting not only the list of predefined metadata and values, but also the values retrieved from the indexed API documents previously created and saved in the registry, along with the usage frequency. The conformance level (Required, Recommended, or Optional) of the suggested metadata is also provided (Figure 1). Semantic annotation of API description. To annotate the parameterValueType and responseDataType metadata elements, the auto-suggestion list also includes persistent semantic URIs from identifiers.org, which enables the referencing of data for the scientific community. While it is possible to extend the semantic annotation to other metadata elements, we have focused on the API’s parameters and responses, which can be considered as the inputs and outputs of the API, respectively.
i Semantic annotation of API parameters is done by annotating parameterValueType with semantic identifiers. We used Elasticsearch to build a suggestion service that takes user search terms from the editor (e.g. hgnc), and uses HTTP requests to GET the list of matching identifiers (e.g. http://identifiers.org/hgnc.symbol). As shown in Figure 2a, this list is appended to the auto-suggestion list retrieved from the previously used identifiers. ii Semantic annotation of API responses is done by annotating responseDataType. We developed the smartAPI profiler, a web application for automatic annotation of web services. We integrated the profiler within the editor. Adding the responseDataType metadata for a specific operation triggers the profiler (Figure 3), which then asks the user to enter example API response data (e.g. http://mygene.info/v3/gene/ 1017). This response data is then recursively traversed to provide a keypath/value pair where the keypath consists of one or more labels concatenated together and the value is either a single value or list of strings. The resource annotation is provided by comparing the keypath labels to resource names and synonyms from identifiers. org. In cases where a match is not found, an example value for the keypath is then compared against resource identifier patterns from identifiers.org, and resulting matches are displayed as suggested annotations. The user may also add his own resource annotation if one does not exist. The annotated API response data is stored in the responseDataType element as an array of YAML objects (Figure 2b). Provide recommendations. The smartAPI editor scans the API document and provides a list of ‘Recommended’ and ‘Optional’ metadata to improve the API interoperability.
We developed a searchable API registry14 to store, index, and view API documents. An API document can be published in the registry directly from the smartAPI editor. The smartAPI registry provides faceted search and displays the list of published APIs along with some details, including the lists of their input/output semantic annotations. 3
The smartAPI ecosystem aims to make Web APIs FAIR, through development of (i) a specification and an editor making API descriptions more Reusable and Accessible, (ii) semantic annotation tools for making APIs more Interoperable, and (iii) a searchable registry for publishing and indexing API descriptions, to achieve more Findable and Reusable APIs. As the next steps, we will implement smartAPI compliant with openAPI13
(b) responseDataType is automatically anno(a) identifiers.org URIs are suggested to semanti- tated by the profiler within the editor (Fig. 3). cally annotate parameterValueType. version 3. Moreover, smartAPI will leverage JSON-LD to provide semantically annotated content that can be treated as Linked Data (http://hdl.handle.net/10421/7478). 4
The smartAPI pilot project was funded as a supplement to CEDAR (U41HG000131521). MyGene.info and MyVariant.info are supported by U01HG008473 (from NHGRI). The LINCS Data Portal is supported by grant U54HL127624 awarded by the National Heart, Lung, and Blood Institute through funds provided by the trans-NIH LINCS Program http://www.lincsproject.org/ and the trans-NIH Big Data to Knowledge (BD2K) initiative https://commonfund.nih.gov/bd2k.