Merge pull request #185 from alien-mcl/issue/99_Add_support_for_descr…

…ibing_headers Added support for describing headers
HydraCG · May 14, 2019 · 638d006 · 638d006
2 parents e40c55c + 4510cac
commit 638d006
Show file tree

Hide file tree

Showing 2 changed files with 59 additions and 0 deletions.
diff --git a/spec/latest/core/core.jsonld b/spec/latest/core/core.jsonld
@@ -64,6 +64,8 @@
     "limit": { "@id": "hydra:limit", "@type": "xsd:nonNegativeInteger" },
     "pageIndex": { "@id": "hydra:pageIndex", "@type": "xsd:nonNegativeInteger" },
     "pageReference": { "@id": "hydra:pageReference" },
+    "returnsHeader": { "@id": "hydra:returnsHeader", "@type": "xsd:string" },
+    "expectsHeader": { "@id": "hydra:expectsHeader", "@type": "xsd:string" },
     "defines": { "@reverse": "rdfs:isDefinedBy" },
     "comment": "rdfs:comment",
     "label": "rdfs:label",
@@ -568,6 +570,24 @@
       "label": "page reference",
       "comment": "Instructs to provide a specific page reference of the collection.",
       "vs:term_status": "testing"
+    },
+    {
+      "@id": "hydra:returnsHeader",
+      "@type": "rdf:Property",
+      "label": "returns header",
+      "comment": "Name of the header returned by the operation.",
+      "domain": "hydra:Operation",
+      "range": "xsd:string",
+      "vs:term_status": "testing"
+    },
+    {
+      "@id": "hydra:expectsHeader",
+      "@type": "rdf:Property",
+      "label": "expects header",
+      "comment": "Specification of the header expected by the operation.",
+      "domain": "hydra:Operation",
+      "range": "xsd:string",
+      "vs:term_status": "testing"
     }
   ]
 }
diff --git a/spec/latest/core/index.html b/spec/latest/core/index.html
@@ -560,6 +560,45 @@ <h3>Documenting a Web API</h3>
       -->
     </pre>
 
+    <p>In addition to expected/returned resources, it is also possible to
+      express similar features for headers with <i>returnsHeader</i> and
+      <i>expectsHeader</i> predicates which provides a simple set of header
+      names. Client SHOULD apply respective header semantics when creating
+      or receiving a request natural for the protocol in use.</p>
+
+    <pre class="example nohighlight" data-transform="returnsHeader"
+         title="Making a use of a returned header">
+      <!--
+      {
+        "@context": "http://www.w3.org/ns/hydra/context.jsonld",
+        "@id": "http://api.example.com/doc/#comments",
+        "@type": "Link",
+        "supportedOperation": [
+          {
+            "@type": "Operation",
+            "method": "POST",
+            ****"expects": "http://api.example.com/doc/#Comment",
+            "returns": "http://api.example.com/doc/#Comment",****
+            "returnsHeader": [
+              "Content-Type",
+              "Content-Length"],
+            "expectsHeader": [
+              "Authorization"
+            ]
+          }
+        ]
+      }
+      -->
+
+      The example above enable an HTTP client to prepare a proper cross-site
+      pre-flight request so the server exposes enlisted headers for the client.
+      The client is also aware of the user authentication requirement necessary
+      for the operation invocation.
+    </pre>
+
+    <p>These are the simple example scenarios and possible usages are not
+      limited to those described above.</p>
+
     <p>Keep in mind that operations specified in an <i>ApiDocumentation</i>
       may fail at runtime as either resources or the <i>ApiDocumentation</i>
       itself have changed since they have been retrieved. Also operation details