Added an example of Api response -> ApiDocumentation flow

HydraCG · Jan 9, 2019 · 8d972da · 8d972da
1 parent 11f0e24
commit 8d972da
Showing 1 changed file with 35 additions and 1 deletion.
diff --git a/spec/latest/core/index.html b/spec/latest/core/index.html
@@ -563,7 +563,7 @@ <h3>Documenting a Web API</h3>
   </section>
 
   <section>
-    <h3>Discovering a Hydra-powered Web API</h3>
+    <a name="discovering-api"></a><h3>Discovering a Hydra-powered Web API</h3>
 
     <p>The first step when trying to access a Web API is to find an entry
       point. Typically, this is done by looking for documentation on the
@@ -630,6 +630,40 @@ <h3>Discovering a Hydra-powered Web API</h3>
       using HTTP Link Headers is typically not necessary as the concepts
       used in responses from the API will dereference to their
       documentation.</p>
+
+    <p>Another case would involve an <i>ApiDocumentation</i> discover from
+      another Api response. There is no restriction on emitting an HTTP
+      <i>Link</i> header on every Api response, thus every response could be
+      used to discover <i>ApiDocumentation</i>.</p>
+
+    <pre class="example nohighlight" data-transform="updateExample"
+         title="Retrieving a Hydra API documentation from another Api response">
+      <!--
+      GET /api/items HTTP/1.1
+      Host: api.example.com
+      Accept: application/ld+json
+
+      ====================================
+
+      HTTP/1.1 200 OK
+      ...
+      Content-Type: application/ld+json
+      ****Link: <http://api.example.com/doc/>; rel="http://www.w3.org/ns/hydra/core#apiDocumentation"****
+
+      {
+        "@context": "http://www.w3.org/ns/hydra/context.jsonld",
+        "@id": "http://api.example.com/api/items",
+        "title": "Items collection",
+        ...
+      }
+      -->
+    </pre>
+
+    <p class="note">It is possible to use a fallback behavior in case an
+      Api response does not present an HTTP <i>Link</i> header. In such a situation,
+      client may use <i>Host</i> HTTP header value that was used to receive a response
+      and obtain an HTTP <i>Link</i> header using an <i>Api discovery</i> mechanism
+      described <a href="#discovering-api">at the beginning of this section</a>.</p>
   </section>
 </section>