A guideline for links

Change-Id: I0b69ed5d52b347684e9eed768600ce04bab51853
Closes-Bug: 1562058

guidelines/http.rst

@@ -80,6 +80,12 @@ in the OpenStack API is critical to the API being compatible with the
 vast range of runtimes, programming languages, and proxy servers (open
 and commercial) that exist in the wild.
 
+HTTP Links
+----------
+
+Including links to resources are an important part of any HTTP API. Links in
+OpenStack APIs conform to the :ref:`links` guideline.
+
 HTTP Response Codes
 -------------------
 

guidelines/links.rst

@@ -0,0 +1,32 @@
+.. _links:
+
+Links
+=====
+
+Links to other resources often need to be represented in responses. There is
+already a well established format for this representation in `JSON
+Hyper-Schema: Hypertext definitions for JSON Schema
+<http://json-schema.org/latest/json-schema-hypermedia.html>`_.
+This is already the `prevailing representation
+<https://wiki.openstack.org/wiki/API_Working_Group/Current_Design/Links>`_ in
+use by a number of prominent OpenStack projects and also in use by the
+:ref:`errors` guideline.
+
+.. note:: Before inventing a new value for ``rel``, please check the existing
+   `Link Relations
+   <http://www.iana.org/assignments/link-relations/link-relations.xhtml>`_ for
+   something you can reuse.
+
+Links Example
+-------------
+
+    .. code-block:: javascript
+
+        {
+          "links": [
+            {
+              "rel": "help",
+              "href": "http://developer.openstack.org/api-ref/compute/#create-server"
+            }
+          ]
+        }

guidelines/microversion_specification.rst

@@ -147,6 +147,8 @@ provided by Nova::
        ]
     }
 
+.. note:: The ``links`` conform to the :ref:`links` guideline.
+
 "max_version" is maximum version, "min_version" is minimum version.
 
 When the requested version is out of range for the server, the server returns