#149 hydra:search with HTTP POST

spec/latest/core/core.jsonld

@@ -247,7 +247,7 @@
       "@id": "hydra:supportedOperation",
       "@type": "hydra:Link",
       "label": "supported operation",
-      "comment": "An operation supported by instances of the specific Hydra class or the target of the Hydra link",
+      "comment": "An operation supported by instances of the specific Hydra class, or the target of the Hydra link, or IRI template.",
       "range": "hydra:Operation",
       "domainIncludes": ["rdfs:Class", "hydra:Class", "hydra:Link", "hydra:TemplatedLink", "hydra:SupportedProperty"],
       "isDefinedBy": "http://www.w3.org/ns/hydra/core",

spec/latest/core/index.html

@@ -1241,13 +1241,92 @@ <h3>Templated Links</h3>
           "@type": "IriTemplate",
           "template": "/{id}",
           "resolveRelativeTo": "LinkContext",
-          "variable": "id",
           "mapping": {...}
         }
       }
       -->
     </pre>
-</section>
+  </section>
+
+  <section>
+    <h3>IRI template operations</h3>
+
+    <p>There are circumstances in which client would like to perform an operation
+      not knowing the final IRI of the resource to be called. This case is especially
+      in force when working with collections - client may want to add a new
+      collection member, or it may need to provide more details while searching
+      with other protocol's method (i.e. POST instead of GET in case of an HTTP).</p>
+
+    <p>This is achievable by attaching a <i>supportedOperation</i> to the property
+      that connects a subject of that relation with its <i>IRI template</i>
+      as described in the previous part of this document. Please note that
+      client is still allowed to use the defined link and custom operation's
+      method is optional.</p>
+
+    <pre class="example nohighlight"
+         data-transform="updateExample"
+         title="Operation with IRI template">
+      <!--
+      {
+        "@context": "http://www.w3.org/ns/hydra/context.jsonld",
+        "@id": "http://api.example.com/api-documentation",
+        "@type": "ApiDocumentation",
+        ****"api:search": {
+          "@type": "Link",
+          "rdfs:subClassOf": "search",
+          "supportedOperation": {
+            "@type": "SupportedOperation",
+            "method": "POST"
+          }****
+      }
+
+      {
+        "@context": "http://www.w3.org/ns/hydra/context.jsonld",
+        "@id": "http://api.example.com/issues",
+        "@type": "Collection",
+        ****"api:search": {
+          "@type": "IriTemplate",
+          "template": "/issues?search={name}",
+          "mapping": {...}****
+      }
+      -->
+    </pre>
+
+    <p>The example above allows client to either invoke an HTTP GET or POST
+      call on <i>http://api.example.com/issues?search=search_string</i> resource.</p>
+
+    <pre class="example nohighlight"
+         data-transform="updateExample"
+         title="Operation with IRI template without link option">
+      <!--
+      {
+        "@context": "http://www.w3.org/ns/hydra/context.jsonld",
+        "@id": "http://api.example.com/api-documentation",
+        "@type": "ApiDocumentation",
+        ****"api:find": {
+          "supportedOperation": {
+            "@type": "SupportedOperation",
+            "method": "POST"
+          }****
+      }
+
+      {
+        "@context": "http://www.w3.org/ns/hydra/context.jsonld",
+        "@id": "http://api.example.com/issues",
+        "@type": "Collection",
+        ****"api:search": {
+          "@type": "IriTemplate",
+          "template": "/issues?find={name}",
+          "mapping": {...}****
+      }
+      -->
+    </pre>
+
+    <p>The example above allows client to invoke only an HTTP POST
+      call on <i>http://api.example.com/issues?find=search_string</i> resource as
+      the described relation of <i>find</i> is neither a subclass of a link nor
+      a link itself.</p>
+  </section>
 
   <section>
     <h3>Description of HTTP Status Codes and Errors</h3>