KC3 Smart API Registry Summary

1M.2.PRODUCT An API Registry for the Definition and Discovery of APIs

In order to leverage and expand on existing standards within the community and to rapidly achieve the open standard API goals of the Data Commons, KC3 has collected and categorized the available APIs associated with the DCPPC. KC3 collectively agreed that DCPPC APIs should be documented at 3 levels;

  1. A high-level summary of all available APIs across the entire DCPPC Consortium (Figure 1),

  2. All DCPPC members will provide all information/metadata from each API, including links. (Appendix 1), and

  3. All DCPPC members will register their APIs in the NIH Data Commons SMART API repository with registration guidelines (http://smart-api.info).

This registry will allow for a community of reusable open APIs across the entire DCPPC. This product will allow for ease of use in finding existing APIs and encourage the development and sharing of new open APIs. This registry has been created and instructions on how to register APIs to the registry has been created and disseminated. Table 1 shows the current status of the number of DCPPC APIs listed at each of the 3 levels.

SmartAPI was agreed on by KC3 team members as the location of the common registry. KC3 has requested that all available DCPPC APIs, across all teams, will be registered to the common http://smart-api.info repository and have a standardized tag of “NIHdatacommons” for easy discovery and retrieval. The first step towards discovery and reuse is to make sure the APIs are well documented and registered in the NIH Data Commons SMART API repository. This major initiative of having APIs registered in the registry will be completed by the end of June and updated as new APIs become available. Now that the registry and instructions for registering has been created, the goal is to collect and categorize all existing APIs (production, development and in plan) across the DCPPC (Figure 1): https://tinyurl.com/DCPPC-APIs-overview. (slide 1).

Number of APIs listed in DCPPC API Overview

(Figure 1)

Number of APIs with listed with Documentation

(Appendix 1)

Number of APIs Registered in SmartAPI
65 14 3

Table 1: Number of DCPPC APIs documented at each of the 3 levels as of 4/23/2018

An overview of Data Commons APIs

Figure 1: Overview of DCPPC APIs (last update 04/18/18). (https://tinyurl.com/DCPPC-APIs-overview slide 1).

Swagger to OpenAPI Converters

1) api-spec-converter

Tool used by Jeff: https://www.npmjs.com/package/api-spec-converter

Convert between API description formats such as Swagger and RAML

Currently only supports conversion to OpenAPI(fka Swagger) 2.0 format, and from OpenAPI 2.0 to OpenAPI 3.0.x

You can also use the online version at https://lucybot-inc.github.io/api-spec-converter/.

Our API is built using a Swagger 2.0 java framework. Swagger.json in the example usage below is a Swagger 2.0 document.

Example Usage:

bash-4.2$ api-spec-converter -f swagger_2 -t openapi_3 swagger.json > openapi3.json

2) swagger2openapi

Tools used by David Steinberg: https://github.com/Mermade/swagger2openapi

In the Data Object Service we were able to convert our schematic representation to OpenAPI3 using the above tool. In the README of our documentation you can see this process:

swagger2openapi -y openapi/data_object_service.swagger.yaml > openapi/data_object_service.openapi.yaml

You can see the original yaml here. We then added specific details to annotate some details of our data model using available ontologies. We also removed DOS endpoints that did not apply to the specific instance, and added the host details.

We added the tag NIHdatacommons and validated and registered the document using SmartAPI.info.

The final SmartAPI version can be seen here.

3) SmartAPI Editor

http://smart-api.info/editor/ is meant to help individuals add the SmartAPI required tags to their spec.

Training and Ongoing Support

KC3 hosted training conducted by Alexander Malic, including an explanation of why to register APIs, on March 23, 2018. Topics included in the training were: what makes a good and smart API (Figure 2), how to create a SmartAPI, and details and examples for registering the SmartAPI for the NIH Data Commons Project. The recording of that training can be viewed here https://drive.google.com/open?id=13Wv3obH9TPNRq_44NofRhDzi8mF0EJYC, and the slides can be accessed at the following link: https://docs.google.com/presentation/d/1fFMWVAF8bptJCnCx_KtggP7SAXplMYCguuhc1kinACs/edit#slide=id.p. Ongoing support will be provided by KC3 and all DCPPC members are encouraged to join the KC3 working group calls for more information or support in registering APIs.

Diagram of OpenAPI, Metadata, Swagger, and FAIR.

Figure 2: Creating a SmartAPI (From Malic, A, 2018 SmartAPI Registry Training).

DCPPC API Registration Progress

Since opening the registry and providing instructions 5 APIs have been registered with the "NIHdatacommons" tag (Figure 3). Each registered API will have to meet specific criteria and required fields, see following link: https://github.com/SmartAPI/smartAPI-Specification/blob/OpenAPI.next/versions/smartapi-list.md. Figures 4-6 represent a full example of the PIC-SURE API registered using SmartAPI. In addition to registering APIs in the SmartAPI repository, we are also collecting and cataloging all API documentation, including links to sandboxes, repositories, and jupyter notebooks from all DCPPC APIs in the following location: Appendix 1. Through collecting this additional information we can further work towards having working, well-documented and FAIR APIs that can be utilized by the consortium to further the work of the NIH Data Commons initiative.

Smart API Registry search for NIHdatacommons tag

Figure 3: SmartAPI Registry - APIs registered with "NIHdatacommons" tag

Example details of an API registered at Smart API

Figure 4: Example of PIC-SURE API registered in SmartAPI registry

Example API documentation

Example API model

Figure 5: Example of API documentation of PIC-SURE API registered in SmartAPI registry

Example API results

FIgure 6: Example of API documentation/metadata of PIC-SURE API registered in SmartAPI registry