Add description for relationship links in api-ref

This adds a section within the index file that describes what a
relationship link is and what it is used for in terms of each
operation within keystone. There will be a relationships section
in both v3 and v3-ext.

This should help clarify any confusion that may arise when a user is
viewing the api-ref about what the relationship links are.

Change-Id: I9c6b7959ed6ea682c565c515af0cf509b6a64e5d
Closes-Bug: #1674676

api-ref/source/v3-ext/index.rst

@@ -4,6 +4,20 @@
  Identity API v3 extensions (CURRENT)
 --------------------------------------
 
+=============
+Relationships
+=============
+
+The entries within the operations below contain a relationship link, which
+appears as a valid URI, however these are actually
+URN (Uniform Resource Name), which are similar to GUID except it uses a URI
+syntax so that it is easier to be read. These links do not resolve to
+anything valid, but exist to show a relationship.
+
+=======================
+Identity API Extensions
+=======================
+
 This page describes these Identity API v3 extensions:
 
 * `OS-ENDPOINT-POLICY API`_

api-ref/source/v3/index.rst

@@ -154,6 +154,19 @@ These features are considered stable as of February 20, 2013.
 - Partial updates are performed using the HTTP ``PATCH`` method
 - Token ID values no longer appear in URLs
 
+=============
+Relationships
+=============
+
+The entries within the operations below contain a relationship link, which
+appears as a valid URI, however these are actually
+URN (Uniform Resource Name), which are similar to GUID except it uses a URI
+syntax so that it is easier to be read. These links do not resolve to
+anything valid, but exist to show a relationship.
+
+=======================
+Identity API Operations
+=======================
 
 This page lists the Identity API operations in the following order: