--- a/paq/prov-aq.html Wed Feb 27 15:33:38 2013 +0000
+++ b/paq/prov-aq.html Wed Feb 27 16:23:27 2013 +0000
@@ -510,8 +510,7 @@
An example request including provenance headers in its response might look like this (where <code>C:</code> and <code>S:</code> prefixes indicate client and server emitted data respectively):
</p>
<pre class="example code">
- C: GET /resource/ HTTP/1.1
- C: Host: http://example.com/
+ C: GET http://example.com/resource/ HTTP/1.1
C: Accept: text/html
S: HTTP/1.1 200 OK
@@ -547,8 +546,7 @@
There may be multiple <code>has_query_service</code> link header fields, and these MAY appear in an HTTP response together with <code>has_provenance</code> link header fields.
</p>
<pre class="example code">
- C: GET /resource/ HTTP/1.1
- C: Host: http://example.com/
+ C: GET http://example.com/resource/ HTTP/1.1
C: Accept: text/html
S: HTTP/1.1 200 OK
@@ -575,8 +573,7 @@
An example transaction using content negotiation and redirection might look like this (where <code>C:</code> and <code>S:</code> prefixes indicate client and server emitted data respectively):
</p>
<pre class="example code">
- C: GET /resource/ HTTP/1.1
- C: Host: http://example.com/
+ C: GET http://example.com/resource/ HTTP/1.1
C: Accept: text/html
S: HTTP/1.1 302 Found
@@ -586,8 +583,7 @@
S: HTML content for http://example.com/resource/
S: is available at http://example.com/resource/content.html
- C: GET /resource/content.html HTTP/1.1
- C: Host: http://example.com/
+ C: GET http://example.com/resource/content.html HTTP/1.1
C: Accept: text/html
S: HTTP/1.1 200 OK
@@ -824,8 +820,8 @@
which might result in an HTTP query for provenance information that looks like this:
</p>
<pre class="example code">
-GET /provenance/service?<b>target</b>=http://www.example.com/entity&<b>steps</b>=2 HTTP/1.1
-Host: example.com</pre>
+GET http://example.com/provenance/service?<b>target</b>=http://www.example.com/entity&<b>steps</b>=2 HTTP/1.1
+</pre>
<p>
(Note that in this case, a "level 3" URI template feature is used [[URI-template]].)
</p>
@@ -988,43 +984,36 @@
The ability to answer forward-looking questions requires some cooperation among the parties who use a resource; for example, a consumer could report use directly to the publisher, or a search engine could discover and report such downstream resource usage. To facilitate such cooperation, a publisher of a resource may implement a "ping-back" capability.
</p>
<p>
- A resource may have an associated "ping-back" URI which can be presented with PROV assertions about the resource. The ping-back URI is associated with a resource using mechanisms similar to those used for presenting a <a class="internalDFN">provenance-URI</a>, but using a <code>pingback</code> link relation instead of <code>has_provenance</code>. A consumer of the resource, or some other system, may perform an HTTP POST operation to the pingback URI where the POST request body contains provenance in one of the recognized provenance formats. For interoperability, a ping-back receiving service SHOULD be able to accept at least PROV-O provenance presented as RDF/XML or Turtle.
+ A resource may have an associated "ping-back" URI which can be presented with references to provenance about the resource. The ping-back URI is associated with a resource using mechanisms similar to those used for presenting a <a class="internalDFN">provenance-URI</a>, but using a <code>pingback</code> link relation instead of <code>has_provenance</code>. A consumer of the resource, or some other system, may perform an HTTP POST operation to the pingback URI, with a request body containing a list of provenance-URIs for provenance records describing uses of the resource.
</p>
<p>
For example, consider a resource that is published by <code>acme.example.com</code>, and is subsequently used by <code>wile-e.example.org</code> in the construction of some new entity; we might see an exchange along the following lines. We start with <code>wile-e.example.org</code> retrieving a copy of <code>acme.example.org</code>'s resource:
</p>
<pre class="pattern">
- C: GET /super-widget HTTP/1.1
- C: Host: acme.example.org
+ C: GET http://acme.example.org/super-widget HTTP/1.1
S: 200 OK
- S: Link: <http://acme.example.org/provenance/super-widget>;
+ S: Link: <http://acme.example.org/super-widget/provenance>;
rel=http://www.w3.org/ns/prov#has_provenance
- S: Link: <http://acme.example.org/pingback/super-widget>;
+ S: Link: <http://acme.example.org/super-widget/pingback>;
rel=http://www.w3.org/ns/prov#pingback
:
(super-widget resource data)</pre>
<p>
- The first of the links in the response is a <code>has_provenance</code> link with a <a class="internalDFN">provenance-URI</a> that has been described previously (<a href="#resource-accessed-by-http" class="sectionRef"></a>). The second is a distinct resource that exists to receive provenance pingbacks. Later, when a new resource has been created or action performed based upon the <code>acme.example.org/super-widget</code>, a client MAY post a pingback request to any supplied <code>prov:pingback</code> URI:
+ The first of the links in the response is a <code>has_provenance</code> link with a <a class="internalDFN">provenance-URI</a> that has been described previously (<a href="#resource-accessed-by-http" class="sectionRef"></a>). The second is a distinct resource that exists to receive provenance pingbacks. Later, when a new resource has been created or action performed based upon the <code>acme.example.org/super-widget</code>, a client MAY post a pingback request to any supplied <code>pingback</code> URI:
</p>
<pre class="example code">
- C: POST /pingback/super-widget HTTP/1.1
- C: Host: acme.example.org
+ C: POST http://acme.example.org/super-widget/pingback HTTP/1.1
C: Content-Type: text/uri-list
C:
C: http://wile-e.example.org/contraption/provenance
C: http://wile-e.example.org/another/provenance
S: 204 No Content
- S: Link: <http://acme.example.org/provenance/super-widget>;
+ S: Link: <http://acme.example.org/super-widget/provenance>;
rel=http://www.w3.org/ns/prov#has_provenance;
anchor="http://acme.example.org/super-widget"
</pre>
-
- <p class="TODO">
- Review.
- Stian's original example returns additional link information - I've removed it for now to focus the example on the essential features, but it could be re-introduced (currently present as comments in HTML source of this document)
- <br/>
<!--
S: Link: <http://wile-e.example.org/contraption/provenance>;
rel=http://www.w3.org/ns/prov#has_provenance;
@@ -1033,41 +1022,41 @@
rel=http://www.w3.org/ns/prov#has_provenance;
anchor=http://acme.example.org/super-widget
-->
- </p>
<p>
The pingback request supplies a list of <a class="internalDFN">provenance-URI</a>s from which forward provenance may be retrieved. The pingback service may do as it chooses with these URIs; e.g., it may choose to save them for later use, to retrieve the associated provenance and save that, to publish the URIs along with other provenance information about the original entity to which they relate, or even to ignore them.
</p>
<p>
- The client MAY further supply <code>#has_query_service</code> <code>Link:</code> headers indicating provenance query services that can describe the target-URI. The anchor MUST be included, and SHOULD be the target-URI of the resource to which this pingback service belongs, or some related resource with relevant provenance.
+ The client MAY further supply <code>has_query_service</code> links indicating provenance query services that can describe the target-URI. The anchor MUST be included, and SHOULD be the target-URI of the resource to which this pingback service belongs, or some related resource with relevant provenance.
</p>
<pre class="example code">
- C: POST http://acme.example.org/pingback/super-widget HTTP/1.1
+ C: POST http://acme.example.org/super-widget/pingback HTTP/1.1
C: Link: <http://wile-e.example.org/sparql>;
rel="http://www.w3.org/ns/prov#has_query_service";
- anchor="http://acme.example.org/pingback/super-widget"
+ anchor="http://acme.example.org/super-widget"
C: Content-Type: text/uri-list
C: Content-Length: 0
C:
S: 204 No Content
- S: Link: <http://acme.example.org/provenance/super-widget>;
+ S: Link: <http://acme.example.org/super-widget/provenance>;
rel=http://www.w3.org/ns/prov#has_provenance;
anchor="http://acme.example.org/super-widget"
</pre>
<p>
In the above example, the client did not submit any provenance-URIs and the URI list is therefore empty.
</p>
- <p>The client MAY similarly include <code>#has_provenance</code> <code>Link:</code> headers to specify a different anchor. The provenance-URIs of those headers SHOULD also be included in the content if the POSTed Content-Type is <code>text/uri-list</code>.
+ <p>The client MAY similarly include <code>has_provenance</code> links to specify provenance records with a different anchor. The provenance-URIs of those headers SHOULD also be included in the content if the POSTed Content-type is <code>text/uri-list</code>.
</p>
<p class="TODO">
- I've downplayed MUST to SHOULD in the last. If the content is empty, should the Content-type be omitted? (see example above). I would be inclined to make it optional, and omit it from the example.
+ Does this SHOULD requirement serve any useful purpose?
</p>
<p>
There is no required information in the server response to a pingback POST request.
- In the examples above, the pingback service responds with an empty response body, and links to provenance for the original resource (note that the <code>Link:</code> header returned contains explicit <code>anchor</code> parameters with the URI of the original resource; without this, the links would relate the indicated URIs to the pingback URI <code>http://acme.example.org/pingback/super-widget</code>).
+ In the examples above, the pingback service responds with an empty response body, and links to provenance for the original resource.
+ (Note that the <code>Link:</code> header returned contains an explicit <code>anchor</code> parameter with the URI of the original resource; without this, the link would relate the indicated URI to the pingback URI <code>http://acme.example.org/super-widget/pingback</code> rather than the original resource.)
</p>
<p>
- The only defined operation on a pingback-URI is POST, which provides links to provenance information or services as described above. A pingback-URI MAY respond to other requests, but no requirements are imposed on how it responds. In particular, it is not specified here how a pingback resource should respond to an HTTP GET request. This leaves open a possibility that the pingback resource MAY have the same URI as the original resource, provided that the original does not respond to POST in some different way.
+ The only defined operation on a pingback-URI is POST, which supplies links to provenance information or services as described above. A pingback-URI MAY respond to other requests, but no requirements are imposed on how it responds. In particular, it is not specified here how a pingback resource should respond to an HTTP GET request. This leaves open a possibility that the pingback resource MAY have the same URI as the original resource, provided that the original does not respond to POST in some different way.
</p>
<!-- also in Stian's proposal