From 2c2d882d6870ef7dbfa4deea1cc4e13d1f1c846e Mon Sep 17 00:00:00 2001 From: Michel Dumontier Date: Wed, 21 Jun 2017 20:33:54 +0200 Subject: [PATCH] first set of updates --- index.html | 728 ++++++++++++++++++++--------------------------------- 1 file changed, 277 insertions(+), 451 deletions(-) diff --git a/index.html b/index.html index 05e6a81..dfd10a2 100644 --- a/index.html +++ b/index.html @@ -2,39 +2,27 @@ smartAPI Specification - - + + - + +
@@ -165,16 +172,14 @@

- You need to have a custom SotD paragraph. Maybe give a succinct description of your spec's status. + This document is a DRAFT that now includes a mapping to v2 and v3 of the OpenAPI specification. It correctly uses vendor extensions. Comments can be provided to the NIH CFWG API Mailing List.

Purpose of the smartAPI Specification

-

The purpose of the smartAPI Specification is to establish a set of standards for the description of metadata elements and values for the description of Application Programming Interfaces (APIs). This document was produced by the Big Data To Knowledge (BD2K) API Interoperability Working Group, one of the NIH Commons Framework Pilot Working Groups. The BD2K API Interoperability Working Group first conducted a survey of API metadata found in existing repositories and guidelines (see Section 2), and subsequently developed the smartAPI Specification as an extension of the Open API Initiative. The Open API Initiative aims to create, develop, and promote an API description format based on the Swagger Specification.

- -

The smartAPI Specification is intended to be a ‘living’ document that will continue to be revised and improved via the input of API development community members.

+

The purpose of the smartAPI Specification is to establish a set of standards for the description of metadata elements and values for the description of Application Programming Interfaces (APIs). This document was produced by the Big Data To Knowledge (BD2K) API Interoperability Working Group, one of the NIH Commons Framework Pilot Working Groups. The BD2K API Interoperability Working Group first conducted a survey of API metadata found in existing repositories and guidelines (see Section 2), and subsequently developed the smartAPI Specification as an extension of the Open API Initiative. The Open API Initiative aims to create, develop, and promote an API description format based on the Swagger Specification.

@@ -182,14 +187,14 @@

Survey of API Metadata in the Wild

This standard is the result of a survey by the BD2K API Interoperability Working Group of existing metadata repositories and specifications that describe APIs. The following eight resources were surveyed:

Repositories: Specifications:
  • Minimal Information About a Software, a key set of minimal fields can that provide maximum value when describing a software.
    • -
  • smartAPI specification, a specification that describes a semantically annotated web service that facilitates discovery and reuse of web-based API.
    • +
  • smartAPI specification, a specification that describes a semantically annotated web service that facilitates discovery and reuse of web-based API.
  • openAPI Initiative, created by a consortium of forward-looking industry experts who recognize the immense value of standardizing on how REST APIs are described.
  • Semantic Automated Discovery and Integration, a set of design patterns defining the behavior of data retrieval and/or analysis resources that must interoperate on the Semantic Web.
  • schema.org API Reference, a reference document for APIs as described by schema.org. @@ -218,515 +223,336 @@

    Audience

-

API Metadata Elements

- -
-

- - - - -

-
-
-

+

API Metadata Elements

-

Name

+

Name [MUST]

A human readable label for the API.

  • Cardinality: 1..1
  • Datatype: string
    • -
-

OpenAPI element: info.title

-
-

- 

 
-          "name": "MyGene.info API"
-
-
-

Must

-
-
+ + 
+		info:

+		  title: mygene.info

+
- -
-

Access Point

-

The base URI for interacting with the API.

-
    -
  • Cardinality: 1..1
    • -
  • Datatype: URI
    • -
-

OpenAPI element: basePath

-
-

- 

 
-          "access point": "http://mygene.info/"
-
-
-

Must

-
-
-
- -
-

Description

-

A human readable description of the service functionality.

+
+

Description [SHOULD]

+

A human readable description of the service.

  • Cardinality: 0..1
  • Datatype: string
-

OpenAPI element: info.description

-
-

- 

 
-          "description": "Documentation of the MyGene.info Gene Query web services. Learn more about [MyGene.info](http://mygene.info/)"
-
-
-

Should

-
-
+ 
+		info:

+		  description: MyGene.info is a high performance API for gene descriptions.
+
+ -
-

Response Mime-Type

-

A list of media types the APIs can produce. This is global to all APIs but can be overridden on specific API calls.

+
+

Descriptors [MAY]

+

Keyword or concepts that describe the API.

  • Cardinality: 0..n
  • Datatype: string
    • -
-

OpenAPI element: produces

-
-

- 

 
-          "produces": "application/json"
-
-
-

Should

-
-
+ + 
 
+        info:
+          x-keywords:
+            - genes
+            - http://semanticscience.org/resource/SIO_010035
+
- -
-

External Docs

-

Documentation page URL for the API.

-
    -
  • Cardinality: 0..n
    • -
  • Datatype: URI
    • -
-

OpenAPI element: externalDocs

-
-

- 

 
-          "documentation": "http://docs.mygene.info/en/v3/"
-
-
-

Should

-
-
-
- -
-

Version

-

The version of the API.

+ +
+

Version [MUST]

+

The version of the API. Specify API version using Semantic Versioning. The major.minor portion of the semver (for example 3.0) SHALL designate the feature set. Typically, .patch versions address errors in the API metadata document, not the feature set.

  • Cardinality: 1..1
  • Datatype: string
-

OpenAPI element: info.version

-
-

- 

 
-          "version": "2.0.0"
-
-
-

Should

-
-
-
+ 
+		info:
+		  version: 2.0.0
+
+
-

Terms of Service

-

A document that describes the terms of use for the API.

+

Terms of Service [MUST]

+

A URL that describes the terms of use for the API.

  • Cardinality: 0..1
    • -
  • Datatype: string
    • +
  • Datatype: URL
-

OpenAPI element: info.termsOfService

-
-

- 

 
-          "terms of service": "http://mygene.info/terms/"
-
-
-

Should

-
-
+ 
+		info:

+		  termsOfService: http://mygene.info/terms/
+
- -
-

SSL Support*

-

Indication of whether SSL Support is present or absent.

-
    -
  • Cardinality: 0..1
    • -
  • Datatype: boolean
    • -
-
-

- 

 
-          "ssl support": "yes"
-
-
-

Should

-
-
-
-
-

Authentication Mode

-

Lists the required security schemes to execute this operation. The object can have multiple security schemes declared in it which are all required.

-
    -
  • Cardinality: 0..1
    • -
  • Datatype: URI
    • -
-

OpenAPI element: securityDefinitions.basicAuth

-
-

- 

 
-          "authentication mode": "none"
-
-
-

Should

-
-
+
+

Access Point [MUST]

+

The base URL for the API upon which the path is added. Also include URL of mirrors that the API is available at.

+
    +
  • Cardinality: 0..1
    • +
  • Datatype: URL
    • +
+ 
+		server:

+		  - url: http://mygene.info/v3/api
+		    description: Production server
+		  - url: https://mygene.info/v3/api
+			description: Fictional HTTPS Production server
+		  - url: http://mirror1.mygene.info/api
+			description: Fictional mirror
+
- -
-

Category*

-

Primary category that the API belongs to.

+ +
+

Response Mime-Type [MUST]

+

A list of media types the APIs can produce. The media type definitions SHOULD be in compliance with RFC6838.

  • Cardinality: 0..n
  • Datatype: string
-
-

- 

 
-          "category": "genetics"
-
-
-

May

-
-
+ 
+        components:

+          responses:

+            - content:

+              - application/json:
+
- + +
-

Website

+

Website [MAY]

A web page that describes the API.

  • Cardinality: 0..1
  • Datatype: URI
-

OpenAPI element: host

-
-

- 

 
-          "website": "http://mygene.info/"
-
-
-

May

-
-
+ 
 
+        info:

+          x-homepage: http://mygene.info
+
- -
-

Publications*

-

Publication ID/URL

+ +
+

Documentation [SHOULD]

+

Additional documentation for the API.

  • Cardinality: 0..n
    • -
  • Datatype: URI
    • -
-
-

- 

 
-          "publications": "Wu C, MacLeod I, Su AI (2013) BioGPS and MyGene.info: organizing online, gene-centric information. Nucl. Acids Res. 41(D1): D561-D565."
-
-
-

May

-
-
-
- -
-

API Access Restrictions*

-

Indicate whether there are restrictions to using the API

-
    -
  • Cardinality: 0..1
    • -
  • Datatype: string
    • -
-
-

- 

 
-          "api access restrictions": "free"
-
-
-

May

-
-
+
  • Datatype: URL
    • + + 
    +		info:
    
+		  documentation: http://docs.mygene.info/en/v3/
+
    -
    -

    Social Media Links*

    -

    Links to social media presence such as Twitter URL, facebook, LinkedIn etc.

    +
    +

    Developer Forum [MAY]

    +

    Forum or Mailing list.

    • Cardinality: 0..n
    • Datatype: URI
    -
    -

    - 

     
-          "social media links": "Twitter: @mygeneinfo"
-
    -
    -

    May

    -
    -
    -
    - -
    -

    Access Point Mirrors*

    -

    URL of the mirror that the API is available at.

    + 
    +       info:
+          x-developerForum: 
+            - https://bitbucket.org/sulab/mygene.hub
+
    +
    + +
    +

    Security [SHOULD]

    +

    Lists the required security schemes to execute this operation. The object can have multiple security schemes declared in it which are all required.

      -
    • Cardinality: 0..n
      • +
    • Cardinality: 0..1
    • Datatype: URI
    -
    -

    - 

     
-          "access point mirrors": "http://mygene.info/v3/api/"
-
    -
    -

    May

    -
    -
    + 
    +		security:
    
+		  - type: apikey
+		    name: api_key
+		    in: header
+
    -
    -

    API Metadata Format*

    -

    Service specification format.

    + + + +
    +

    Access Restrictions [MAY]

    +

    Indicate whether there are restrictions to using the API. Values to use: none, limited, fee.

      -
    • Cardinality: 0..n
      • +
    • Cardinality: 0..1
    • Datatype: string
      • -
    -
    -

    - 

     
-          "api metadata format": "openAPI" 
-
    -
    -

    May

    -
    -
    -
    - -
    -

    API Access Mode*

    -

    The protocols used to access the API

    + + 
     
+        info:
    
+          x-accessRestrictions: 
+           - none
+
    +
    + +
    +

    Social Media [MAY]

    +

    Links to social media presence such as Twitter, Facebook, LinkedIn, GitHub, etc.

    • Cardinality: 0..n
      • -
    • Datatype: string
      • +
    • Datatype: URI
    -
    -

    - 

     
-          "api access mode": "REST"
+    	
     
+        info:
    
+          x-accounts:
    
+            - name: twitter
    
+              accountid: mygeneinfo
    
         
    
-       
    
-		
    May
    
-	    
    
-
    -
    +
    -

    API Location*

    -

    Location, city and country of the API.

    +

    Location [MAY]

    +

    Location, city and country of the server hosting the API.

    • Cardinality: 0..1
    • Datatype: URI
    -
    -

    - 

     
-          "api location": "USA"
+    	
     
+         server:
    
+           - url: http://mygene.info/v3/api
    
+             x-location: USA
         
    
-       
    
-		
    May
    
-	    
    
-
    - +
    -

    API Implementation Language*

    +

    Implementation Language [MAY]

    Language the API was written in.

    • Cardinality: 0..n
    • Datatype: string
    -
    -

    - 

     
-          "api implementation language": "python"
-
    -
    -

    May

    -
    -
    + 
     
+        info:
    
+          x-implementationLanguage: python
+
    -

    API Maturity*

    -

    Maturity of the API.

    +

    Maturity [MAY]

    +

    Maturity of the API. Values to use: development, production.

    • Cardinality: 0..1
    • Datatype: enum
    -
    -

    - 

     
-          "api maturity": "stable"
-
    -
    -

    May

    -
    -
    + 
     
+        info:
    
+          x-maturity: production
+
    -
    -
    + +
    +

    Publications [MAY]

    +

    Publications that describe the API.

    +
      +
    • Cardinality: 0..n
      • +
    • Datatype: URI
      • +
    + 
     
+        info:
    
+          x-publications: 
+            - https://doi.org/10.1093/nar/gks1114
+
    +
    + +
    +

    Funding [MAY]

    +

    Indicate sources of funding.

    +
      +
    • Cardinality: 0..n
      • +
    • Datatype: string
      • +
    + 
     
+        info:
    
+          x-funding:
    
+            - name: National Institutes of Health
+              x-id: https://www.wikidata.org/wiki/Q390551
+              funding-id: HG008473
+
    +
    +
    + +

    Service Provider Metadata

    -

    Responsible Organization

    -

    The identifying name of the contact person/organization.

    +

    Responsible Organization [MUST]

    +

    Provide the name of the organization responsible for the service.

      -
    • Cardinality: 1..1
      • +
    • Cardinality: 1..n
    • Datatype: string
      • -
    -

    OpenAPI element: contact.url

    -
    -

    - 

     
-          "responsible organization": "The Scripps Research Institute"
+	  
+  	  
     
+        info:
    
+          contact:
    
+            - name: The Scripps Research Institute
+              x-id: https://www.wikidata.org/wiki/Q793867
+              x-role: responsible organization
+              url: http://www.scripps.edu/
         
    
-       
    
-		
    Must
    
-	    
    
-
    -

    Responsible Developer

    -

    Name of the developer (User ORCID ID/Name)

    +

    Responsible Developer [MUST]

    +

    Provide the name, ID and email for the responsible developer.

    • Cardinality: 1..1
    • Datatype: URI
    -
    -

    - 

     
-          "responsible developer": "http://orcid.org/0000-0002-2629-6124"
+  	  
     
+        info:
    
+          contact:
    
+            - name: Chunlei Wu
+              x-id: https://orcid.org/0000-0002-2629-6124
+              x-role: responsible developer
+              email: cwu@scripps.edu
         
    
-       
    
-		
    Must
    
-	    
    
-
    -
    - -
    -

    Contact Email

    -

    An e-mail address where the provider of the service may be contacted. MUST be in the format of an email address.

    -
      -
    • Cardinality: 1..1
      • -
    • Datatype: email
      • -
    -

    OpenAPI element: contact.email

    -
    -

    - 

     
-          "contact email": "cwu@scripps.edu" 
-
    -
    -

    Must

    -
    -
    -
    +
    -

    Contributor*

    -

    Contributor person or institute

    +

    Contributor [MAY]

    +

    Indicate any other contributor to the conception, development, or support of the API.

    • Cardinality: 0..1
    • Datatype: string
    -
    -

    - 

     
-          "contributor": "Andrew Su"
-
    -
    -

    May

    -
    -
    -
    - -
    -

    Funding*

    -

    Source of funding.

    -
      -
    • Cardinality: 0..n
      • -
    • Datatype: string
      • -
    -
    -

    - 

     
-          "funding": "NIH"
-
    -
    -

    May

    -
    -
    -
    - -
    -

    Developer Forum*

    -

    Forum or Mailing list.

    -
      -
    • Cardinality: 0..n
      • -
    • Datatype: URI
      • -
    -
    -

    - 

     
-          "developer forum": "https://bitbucket.org/sulab/mygene.hub" 
-
    -
    -

    May

    -
    -
    + 
     
+        info:
    
+          contact:
    
+            - name: Andrew Su
+              x-id: https://orcid.org/0000-0002-9859-4104
+              x-role: contributor
+              email: asu@scripps.edu
+
    -
    +

    API Operation Metadata

    -

    Operation Title*

    -

    Title of the operation. A unique identifier of the operation.

    +

    Operation Identifier

    +

    A unique identifier for the operation.

    • Cardinality: 1..1
    • Datatype: string
      • -
    -
    -

    - 

     
+	  
+  	  
     
+        paths:
+          - get:
+             - 
           "operation title": "q"