Link Relation api rel value

[bpedro]

This PR introduces a change to the API Discovery Format v0.14 [1] §3.8 (Link relation) by creating a new version (v0.15).

Currently, the Link Relation section states that the rel attribute is describedby. This attribute value is part of the POWDER recommendation and is used to "facilitate linking between a described resource and a POWDER document" [2].

While this value fits the purpose of the link relation, it doesn't give any specific API related context to the declaration. In my opinion there should be a rel value that would specifically declare that the linked resource describes an API. There are several other examples following this approach, e.g., the attachment, feed and sitemap rel values, among others [3].

I thus propose to have a specific rel value that specifically declares that the link is an API. This rel value is simply called api and can be used in combination with the existing APIs.json format rel link. Here's the rewritten §3.8 (Link relation):

3.8. Link Relation     

  In order for a Web site to reference its API description, it is recommended that it includes a header or 
  in-line reference to the APIs.json resource using the api link relation, e.g.: 

    * <link rel="api" type="application/apis+json" href="https://example.com/apis.json" />

For reference, here's a unified diff between v0.14 and v0.15 (what this PR proposes):

--- apisjson_0.14.txt   2015-04-29 12:34:09.000000000 +0200
+++ apisjson_0.15.txt   2015-04-29 12:59:39.000000000 +0200
@@ -1,9 +1,9 @@
 Draft for Comment                                  
 Name: API Discovery Format                             
 Informal Name: APIs.json   
-Authors: Kin Lane, Steven Willmott, Nicolas Grenie                                 
-Date: 10/06/2014
-Location: http://apicommons.org/apisjson/apisjson_v0.14.txt
+Authors: Kin Lane, Steven Willmott, Nicolas Grenie, Bruno Pedro
+Date: 29/04/2015
+Location: http://apicommons.org/apisjson/apisjson_v0.15.txt

                A Simple Format for Publishing API Meta Data on the Web

@@ -259,12 +259,10 @@

 3.8. Link Relation     

-  In order for an API to reference its own description, it is recommended that it include header or 
-  in-line references to the APIs.json file using the existing described by link relation: 
+  In order for a Web site to reference its API description, it is recommended that it includes a header or 
+  in-line reference to the APIs.json resource using the api link relation, e.g.: 

-    * <link rel="describedby" href="api.example.com/apis.json" />
-
-  [Note, this is a generic link relation but seems to fit the bill]
+    * <link rel="api" type="application/apis+json" href="https://example.com/apis.json" />

 3.9. Extensions

@@ -287,7 +285,7 @@
      "created": "2014-04-07",
      "modified": "2014-07-09",
      "url": "http://apievangelist.com/apis.json",
-     "SpecificationVersion": "0.14",
+     "SpecificationVersion": "0.15",
      "apis": [
        {
          "name": "Analysis",
@@ -496,4 +494,4 @@
  * organizationUrl 
  * address 
  * phoneNumber 
- * image 
\ No newline at end of file
+ * image

Please give any feedback on this change.

References:

[1] API Discovery Format v0.14, http://apicommons.org/apisjson/apisjson_v0.14.txt

[2] Protocol for Web Description Resources (POWDER): Description Resources, W3C, §4.1, http://www.w3.org/TR/powder-dr/#assoc-linking

[3] Microformats existing rel values, http://microformats.org/wiki/existing-rel-values