Skip to content

Commit eff8906

Browse files
amrapalijzamrapalijz
authored
Update index.html
Minor fixes, re-ordering
1 parent 344ca31 commit eff8906

File tree

1 file changed

+46
-61
lines changed

1 file changed

+46
-61
lines changed

‎index.html

Lines changed: 46 additions & 61 deletions
Original file line numberDiff line numberDiff line change
@@ -58,10 +58,11 @@
5858
company : "Stanford University, USA",
5959
companyURL : "dumontierlab.stanford.edu"
6060
},
61-
{
61+
{
6262
name : "Kathleen Jagodnik",
6363
url : "mailto:[email protected]",
64-
company : "NASA Glenn Research Center, USA",
64+
company : "Icahn School of Medicine at Mount Sinai, USA",
65+
companyURL : "http://labs.icahn.mssm.edu/maayanlab/"
6566
}
6667
],
6768

@@ -143,7 +144,7 @@ <h3>Vision for API Interoperability</h3>
143144

144145
<p><i><u>Modular.</u></i> In order to facilitate the interaction between a client and different APIs, as well as the process to design and describe them, we propose to build Web APIs out of reusable features rather than as monolithic structures. A feature is an independent part of an interface that identifies, describes, and affords a certain kind of interaction across Web APIs. Through repositories of features, and by encouraging their reuse, APIs with similar functional blocks can provide the same features as others. For example, functionality to navigate and/or edit lists of things is present in many APIs, but currently exposed through many different interfaces. By reusing a generic feature for lists, a client designed for the list feature can use any of those APIs as opposed to only one. This means we can focus our descriptive efforts on features rather than APIs, and the description of features can be reused across APIs. In addition, features can be tested and evaluated for performance under varying circumstances, such that API designers can estimate the impact of incorporating a certain feature, whereas this currently only surfaces after implementation and usage.</p>
145146

146-
<p>The <a href="https://openapis.org/">Open API Initiative</a> aims to create, develop, and promote an API description format based on the Swagger Specification. The BD2K API Interoperability working group has reviewed that standard by conducting a survey of metadata use in the real world (refer to Survey of API Metadata in the Wild section below), and has developed the smartAPI Specification as an extension of the Open API Initiative. The smartAPI Specification includes 19 metadata elements beyond those included in the Open API Initiative. Examples of the 19 elements are category to which the API belongs, metadata format and access mode at the API metadata level, the parameter type and parameter value type at the operation parameter level, and the conformance to a specified response profile at the operation response level.</p>
147+
<p>The <a href="https://openapis.org/" target="_blank">Open API Initiative</a> aims to create, develop, and promote an API description format based on the Swagger Specification. The BD2K API Interoperability working group has reviewed that standard by conducting a survey of metadata use in the real world (refer to Survey of API Metadata in the Wild section below), and has developed the smartAPI Specification as an extension of the Open API Initiative. The smartAPI Specification includes 19 metadata elements beyond those included in the Open API Initiative. Examples of the 19 elements are category to which the API belongs, metadata format and access mode at the API metadata level, the parameter type and parameter value type at the operation parameter level, and the conformance to a specified response profile at the operation response level.</p>
147148

148149
<p>Because every API currently requires unique hardcoded clients, the costs of development are consequently inflated and compatibility across APIs is hindered (Verborgh and Dumontier 2016). To address these shortcomings, the smartAPI Specification aims to establish a universal standard that can be employed by API developers.</p>
149150
</p>
@@ -162,29 +163,28 @@ <h3>Survey of API Metadata in the Wild</h3>
162163
<p>This Standard is the result of a survey by the Working Group of existing metadata repositories and specifications that describe APIs. The following eight resources were surveyed:</p>
163164

164165
<ul><i>Repositories:</i>
165-
<li><a href="http://biocatalogue.org">Biocatalogue</a>, a registry of biological web services with 1,184 services.</li>
166-
<li><a href="http://www.programmableweb.com/apis/directory">Programmable Web</a>, a directory of internet-based APIs with over 15,000 API descriptions.</li>
167-
<li><a href="https://bio.tools/">Tools & Data Services Registry</a>, a registry with information about analytical tools and data services for bioinformatics with 2,331 entries.</li>
166+
<li><a href="http://biocatalogue.org" target="_blank">Biocatalogue</a>, a registry of biological web services with 1,184 services.</li>
167+
<li><a href="http://www.programmableweb.com/apis/directory" target="_blank">Programmable Web</a>, a directory of internet-based APIs with over 15,000 API descriptions.</li>
168+
<li><a href="https://bio.tools/" target="_blank">Tools & Data Services Registry</a>, a registry with information about analytical tools and data services for bioinformatics with 2,331 entries.</li>
168169
</ul>
169170
<ul><i>Specifications:</i>
170-
<li><a href="http://www.softwarediscoveryindex.org/">Minimal Information About a Software</a>, a key set of minimal fields can that provide maximum value when describing a software.</li>
171-
<li><a href="http://smart-api.info/website/docs/specification/">smartAPI specification</a>, a specification that describes a semantically annotated web service that facilitates discovery and reuse of web-based API.</li>
172-
<li><a href="https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.md">openAPI Initiative</a>, created by a consortium of forward-looking industry experts who recognize the immense value of standardizing on how REST APIs are described.</li>
173-
<li><a href="https://rawgit.com/wilkinsonlab/SADI-Specification/master/SADI-W3C-Member-Submission.html#service-metadata">Semantic Automated Discovery and Integration</a>, a set of design patterns defining the behavior of data retrieval and/or analysis resources that must interoperate on the Semantic Web.</li>
171+
<li><a href="http://www.softwarediscoveryindex.org/" target="_blank">Minimal Information About a Software</a>, a key set of minimal fields can that provide maximum value when describing a software.</li>
172+
<li><a href="http://smart-api.info/website/docs/specification/" target="_blank">smartAPI specification</a>, a specification that describes a semantically annotated web service that facilitates discovery and reuse of web-based API.</li>
173+
<li><a href="https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.md" target="_blank">openAPI Initiative</a>, created by a consortium of forward-looking industry experts who recognize the immense value of standardizing on how REST APIs are described.</li>
174+
<li><a href="https://rawgit.com/wilkinsonlab/SADI-Specification/master/SADI-W3C-Member-Submission.html#service-metadata" target="_blank">Semantic Automated Discovery and Integration</a>, a set of design patterns defining the behavior of data retrieval and/or analysis resources that must interoperate on the Semantic Web.</li>
174175
<li><a href="https://schema.org/APIReference">schema.org API Reference</a>, a reference document for APIs as described by schema.org.
175176
</ul>
176177

177178
<p>We subsequently aggregated all the metadata elements from all eight resources to produce a common list of 63 API metadata elements. We further divided these elements into five categories:
178179
<ul>
179-
<li>API metadata: 20 elements</li>
180-
<li>Service Provider metadata: six elements</li>
181-
<li>API Operation metadata: 10 elements</li>
182-
<li>Operation Parameter metadata: 12 elements</li>
183-
<li>Operation Response metadata: six elements</li>
184-
</ul>
180+
<li><a href="#apimd">API Metadata</a>: 20 elements</li>
181+
<li><a href="#spmd">Service Provider Metadata</a>: 6 elements</li>
182+
<li><a href="#aomd">API Operation Metadata</a>: 10 elements</li>
183+
<li><a href="#opmd">Operation Parameter Metadata</a>: 12 elements</li>
184+
<li><a href="#ormd">Operation Response Metadata</a>: 6 elements</li>
185185
</p>
186186

187-
<p>Next, we discussed each of the metadata field amongst the working group members to re-evaluate its applicability and relevance and further classified them into whether it MUST, SHOULD, or MAY be included in the API description. The cardinality and datatype of metadata field were further specified along with a description and example. The results of the survey are available <a href="https://goo.gl/wKR51W">here</a>. The key words "MUST", "SHOULD", and "MAY" in this document are to be interpreted as described in <a href="http://www.ietf.org/rfc/rfc2119.txt">RFC 2119</a>.</p>
187+
<p>Next, we discussed each of the metadata field amongst the working group members to re-evaluate its applicability and relevance and further classified them into whether it MUST, SHOULD, or MAY be included in the API description. The cardinality and datatype of metadata field were further specified along with a description and example. The results of the survey are available <a href="https://goo.gl/wKR51W" target="_blank">here</a>. The key words "MUST", "SHOULD", and "MAY" in this document are to be interpreted as described in <a href="http://www.ietf.org/rfc/rfc2119.txt" target="_blank">RFC 2119</a>.</p>
188188
</section>
189189

190190
<section>
@@ -198,38 +198,23 @@ <h2>Audience</h2>
198198
<h2>Vision for the Implementation for the smartAPI specification</h2>
199199
<p>The ultimate aim of the BD2K API Interoperability Working Group is to develop a strategy for maximizing interoperability and reuse of web-based biomedical APIs. The widespread adoption of the smartAPI Specification by the community promises to improve the efficiency and lower the costs of API development, promoting cross-API compatibility and resolving current challenges in API usage.</p>
200200

201-
<p>Information about the implementation of the smartAPI Specification and options for enhancing API interoperability is available <a href="https://docs.google.com/document/d/1Jr8a2R9CaxgpZoSrC6JeHFBg4x8SRBrxxsFc4_Ozzc8/edit#">here</a>.</p>
202-
</section>
203-
204-
<section>
205-
<h2>Metadata Elements</h2>
206-
<p>
207-
Five Categories:
208-
<ul>
209-
<li><a href="#apimd">API Metadata</a></li>
210-
<li><a href="#spmd">Service Provider Metadata</a></li>
211-
<li><a href="#aomd">API Operation Metadata</a></li>
212-
<li><a href="#opmd">Operation Parameter Metadata</a></li>
213-
<li><a href="#ormd">Operation Response Metadata</a></li>
214-
</ul>
215-
</p>
201+
<p>Information about the implementation of the smartAPI Specification and options for enhancing API interoperability is available <a href="https://docs.google.com/document/d/1Jr8a2R9CaxgpZoSrC6JeHFBg4x8SRBrxxsFc4_Ozzc8/edit#" target="_blank">here</a>.</p>
216202
</section>
217-
218-
<script type="text/javascript"> if (window.showTocToggle) { var tocShowText = "show"; var tocHideText = "hide"; showTocToggle(); } </script>
219-
<div class="buttonpanel">
220-
<form action=""><p>
221-
<input id="show-sd" onclick="set_display_by_class('div','image','none'); set_display_by_id('hide-sd',''); set_display_by_id('show-sd','none');" type="button" value="Hide Diagrams" />
222-
<input id="hide-sd" onclick="set_display_by_class('div','image',''); set_display_by_id('hide-sd','none'); set_display_by_id('show-sd','');" style="display: none" type="button" value="Show Diagrams" />
223-
<input id="hide-examples" onclick="set_display_by_class('div','example','none'); set_display_by_id('hide-examples','none'); set_display_by_id('show-examples','');" type="button" value="Hide Examples" />
224-
<input id="show-examples" onclick="set_display_by_class('div','example',''); set_display_by_id('hide-examples',''); set_display_by_id('show-examples','none');" style="display: none" type="button" value="Show Examples" />
225-
<input id="hide-json" onclick="show_syntaxes(bFSSVisible,false); set_display_by_id('hide-json','none'); set_display_by_id('show-json','');" style="display: none" type="button" value="Hide JSON in Examples" />
226-
<input id="show-json" onclick="show_syntaxes(bFSSVisible,true); set_display_by_id('hide-json',''); set_display_by_id('show-json','none');" type="button" value="Show JSON in Examples" />
227-
</p>
228-
</form>
229-
</div>
230203

231204
<section id="apimd">
232205
<h2>API Metadata</h2>
206+
<script type="text/javascript"> if (window.showTocToggle) { var tocShowText = "show"; var tocHideText = "hide"; showTocToggle(); } </script>
207+
<div class="buttonpanel">
208+
<form action=""><p>
209+
<input id="show-sd" onclick="set_display_by_class('div','image','none'); set_display_by_id('hide-sd',''); set_display_by_id('show-sd','none');" type="button" value="Hide Diagrams" />
210+
<input id="hide-sd" onclick="set_display_by_class('div','image',''); set_display_by_id('hide-sd','none'); set_display_by_id('show-sd','');" style="display: none" type="button" value="Show Diagrams" />
211+
<input id="hide-examples" onclick="set_display_by_class('div','example','none'); set_display_by_id('hide-examples','none'); set_display_by_id('show-examples','');" type="button" value="Hide Examples" />
212+
<input id="show-examples" onclick="set_display_by_class('div','example',''); set_display_by_id('hide-examples',''); set_display_by_id('show-examples','none');" style="display: none" type="button" value="Show Examples" />
213+
<input id="hide-json" onclick="show_syntaxes(bFSSVisible,false); set_display_by_id('hide-json','none'); set_display_by_id('show-json','');" style="display: none" type="button" value="Hide JSON in Examples" />
214+
<input id="show-json" onclick="show_syntaxes(bFSSVisible,true); set_display_by_id('hide-json',''); set_display_by_id('show-json','none');" type="button" value="Show JSON in Examples" />
215+
</p>
216+
</form>
217+
</div>
233218
<p>
234219
<table>
235220
<thead>
@@ -293,7 +278,7 @@ <h2>API Metadata</h2>
293278
<tr>
294279
<td><a href="#website">Website</a></td>
295280
<td>A web page that describes the API.</td>
296-
<td>SHOULD</td>
281+
<td>MAY</td>
297282
</tr>
298283
<tr>
299284
<td><a href="#publications">Publications</a></td>
@@ -1089,7 +1074,7 @@ <h3>Operation Parameter Description</h3>
10891074
</pre>
10901075
</p>
10911076
<div class="image">
1092-
<p><img alt="May" border="0" height="60" src="may.jpg" width="60" /><br/></p>
1077+
<p><img alt="May" border="0" height="60" src="must.jpg" width="60" /><br/></p>
10931078
</div>
10941079
</div>
10951080
</section>
@@ -1291,7 +1276,7 @@ <h3>Response Header</h3>
12911276
</pre>
12921277
</p>
12931278
<div class="image">
1294-
<p><img alt="Should" border="0" height="60" src="should.jpg" width="80" /><br/></p>
1279+
<p><img alt="Should" border="0" height="60" src="may.jpg" width="80" /><br/></p>
12951280
</div>
12961281
</div>
12971282
</section>
@@ -1351,42 +1336,42 @@ <h2>Acknowledgements</h2>
13511336
<h2>Appendix</h2>
13521337
<p>Relevant Standards
13531338
<ul>
1354-
<li>Open description format for APIs (<a href="https://openapis.org/">https://openapis.org/</a>)</li>
1355-
<li>W3C community group for hypermedia-driven APIs in RDF (<a href="http://www.hydra-cg.com/">http://www.hydra-cg.com/</a>)</li>
1356-
<li>Hydra hypermedia descriptions (<a href="https://www.hydra-cg.com/spec/latest/core/">https://www.hydra-cg.com/spec/latest/core/</a>)</li>
1357-
<li>SADI framework for semantic web services (<a href="https://rawgit.com/wilkinsonlab/SADI-Specification/master/SADI-W3C-Member-Submission.html">https://rawgit.com/wilkinsonlab/SADI-Specification/master/SADI-W3C-Member-Submission.html</a>)</li>
1339+
<li>Open description format for APIs (<a href="https://openapis.org/" target="_blank">https://openapis.org/</a>)</li>
1340+
<li>W3C community group for hypermedia-driven APIs in RDF (<a href="http://www.hydra-cg.com/" target="_blank">http://www.hydra-cg.com/</a>)</li>
1341+
<li>Hydra hypermedia descriptions (<a href="https://www.hydra-cg.com/spec/latest/core/" target="_blank">https://www.hydra-cg.com/spec/latest/core/</a>)</li>
1342+
<li>SADI framework for semantic web services (<a href="https://rawgit.com/wilkinsonlab/SADI-Specification/master/SADI-W3C-Member-Submission.html" target="_blank">https://rawgit.com/wilkinsonlab/SADI-Specification/master/SADI-W3C-Member-Submission.html</a>)</li>
13581343
</ul>
13591344
</p>
13601345

13611346
<p>APIs Represented
13621347
<ul>
13631348
<li>MyGene.info - aggregated high-performance gene annotation API</li>
13641349
<ul>
1365-
<li>API: http://mygene.info/v2/api/</li>
1366-
<li>Docs: http://docs.mygene.info</li>
1350+
<li>API: <a href="http://mygene.info/v2/api/" target="_blank">http://mygene.info/v2/api/</a></li>
1351+
<li>Docs: <a href="http://docs.mygene.info" target="_blank">http://docs.mygene.info</a></li>
13671352
</ul>
13681353

13691354
<li>MyVariant.info - aggregated high-performance human variant annotation API</li>
13701355
<ul>
1371-
<li>API: http://myvariant.info/v1/api/</li>
1372-
<li>Docs: http://docs.myvariant.info</li>
1356+
<li>API: <a href="http://myvariant.info/v1/api/" target="_blank">http://myvariant.info/v1/api/</a></li>
1357+
<li>Docs: <a href="http://docs.myvariant.info" target="_blank">http://docs.myvariant.info</a></li>
13731358
</ul>
13741359
<li>Openlifedata.org - a portal to biomedical linked data</li>
13751360
<ul>
1376-
<li>API: http://apidocs.openlifedata.org/openlifedata</li>
1361+
<li>API: <a href="http://apidocs.openlifedata.org/openlifedata" target="_blank">http://apidocs.openlifedata.org/openlifedata</a></li>
13771362
</ul>
13781363
<li>PrefixCommons.org - aggregated API for prefixes, identifiers, IRI’s and URLs</li>
13791364
<ul>
1380-
<li>API: http://api.prefixcommons.org</li>
1365+
<li>API: <a href="http://api.prefixcommons.org" target="_blank">http://api.prefixcommons.org</a></li>
13811366
</ul>
13821367
<li>XNAT - Medical Imaging Data Management</li>
13831368
<ul>
1384-
<li>Docs: https://wiki.xnat.org/display/XNAT16/XNAT+REST+API+Directory</li>
1385-
<li>API: https://central.xnat.org/</li>
1369+
<li>Docs: <a href="https://wiki.xnat.org/display/XNAT16/XNAT+REST+API+Directory" target="_blank">https://wiki.xnat.org/display/XNAT16/XNAT+REST+API+Directory</a></li>
1370+
<li>API: <a href="https://central.xnat.org" target="_blank">https://central.xnat.org/</a></li>
13861371
</ul>
13871372
<li>NDA - NIMH Data Archive Data Dictionary API</li>
13881373
<ul>
1389-
<li>API: https://ndar.nih.gov/api/datadictionary/v2/</li>
1374+
<li>API: <a href="https://ndar.nih.gov/api/datadictionary/v2/" target="_blank">https://ndar.nih.gov/api/datadictionary/v2/</a></li>
13901375
</ul>
13911376
</p>
13921377
</section>

0 commit comments

Comments
 (0)