Skip to content

Commit

Permalink
Editorial fixes
Browse files Browse the repository at this point in the history 
Formatting of §1.2
Moved ISSUE-382 to immediately after ISSUE-380 and added some clarifying text
Put HTTP OPTIONS and HTTP GET/HEAD into their own subsections
Moved ISSUE 516 (OAI-PMH as QSA implementation) to immediately after ISSUE-511 (support for existing QSA parameter names)
§6.3: Added an issue that this will be completed
Some minor fixes (& -> & typos, highlighting etc.)
  • Loading branch information
@larsgsvensson
larsgsvensson committed Oct 30, 2018
1 parent 0bf2a2b commit 3b53c23
Showing 1 changed file with 65 additions and 35 deletions.
100 changes: 65 additions & 35 deletions conneg-by-ap/index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -72,8 +72,10 @@ <h3>Compliance with this Document</h3>
<section id="notationalconventions">
<h3>Notational Conventions</h3>
<p>
The key words <dfn>may</dfn>, <dfn>MUST</dfn>, <dfn>MUST NOT</dfn>, <dfn>OPTIONAL</dfn>, <dfn>SHALL</dfn>,
<dfn>SHALL NOT</dfn>, <dfn>SHOULD</dfn>, <dfn>SHOULD NOT</dfn>, <dfn>RECOMMENDED</dfn>, <dfn>REQUIRED</dfn>,
The key words <em class="rfc2119">MAY</em>, <em class="rfc2119">MUST</em>, <em class="rfc2119">MUST NOT</em>,
<em class="rfc2119">OPTIONAL</em>, <em class="rfc2119">SHALL</em>, <em class="rfc2119">SHALL NOT</em>,
<em class="rfc2119">SHOULD</em>, <em class="rfc2119">SHOULD NOT</em>, <em class="rfc2119">RECOMMENDED</em>,
and <em class="rfc2119">REQUIRED</em>,
in this document are to be interpreted as described in [[RFC2119]].
</p>
</section>
Expand Down Expand Up @@ -153,12 +155,22 @@ <h2>Related Work</h2>
current version of the draft (-00) is expected to be completely re-written in course of the process and should
not be seen as anything but work-in-progress.
</p>
<div class="issue" data-number="380"></div>
<p class="issue" data-number="380">
The Internet-Draft for the registration of
<code>Accept-Profile</code> and <code>Content-Profile</code>
is currently work-in progress.
When that work is completed, the above text will be adjusted accordingly
or deleted.
</p>
<p class="issue" data-number="382">
Previous uses of <code>Accept-*</code> headers
or other HTTP headers for this use
will be listed and discussed here.
</p>
<p>
Describing the parts of profiles and their relation to other profiles is done within the Profiles Ontology
[[PROF-ONT]], also produced by the DXWG.
</p>
<div class="issue" data-number="382"></div>
<div class="issue" data-number="383"></div>
<div class="issue" data-number="384"></div>
<div class="issue" data-number="514"></div>
Expand Down Expand Up @@ -348,8 +360,9 @@ <h2>Realisations</h2>
<h3>Hypertext Transfer Protocol</h3>
<p>
A realisation of the Abstract Model using the Hypertext Transfer Protocol (HTTP) is presented here.
This implementation is based on HTTP content negotiation and uses two new HTTP headers, „Accept-Profile“
and „Content-Profile“ that are to be defined in an upcoming Internet-Draft [[PROF-IETF]].
This implementation is based on HTTP content negotiation and uses two new HTTP headers,
<code>Accept-Profile</code> and <code>Content-Profile</code>
that are to be defined in an upcoming Internet-Draft [[PROF-IETF]].
</p>
<p>
Content Negotiation by profile adds a further dimension to the already existing HTTP content
Expand All @@ -363,21 +376,29 @@ <h3>list profiles</h3>
<p>
Listing profiles for a resource using HTTP can be done in two ways.
</p>
<div class="issue" data-number="510"></div>
<p>
The first one is to issue an <code>OPTIONS</code> request against the resource. In this case a server implementing
content negotiation by profile SHOULD return a <code>Content-Profile</code> header listing all profiles
the requested resource conforms to.
</p>
<pre class="example nohighlight" title="Using HTTP OPTIONS to list available profiles" aria-busy="false" aria-live="polite">
<section id="listprofileshttpoptions">
<h4>Using <code>HTTP OPTIONS</code></h4>
<p class="issue" data-number="510">
The use of <code>HTTP OPTIONS</code> is discouraged
since the responses are not cacheable.
</p>
<p>
The first one is to issue an <code>OPTIONS</code> request against the resource.
In this case a server implementing content negotiation by profile
SHOULD return a <code>Content-Profile</code> header
listing all profiles the requested resource conforms to.
</p>
<pre class="example nohighlight" title="Using HTTP OPTIONS to list available profiles" aria-busy="false" aria-live="polite">
OPTIONS /some/resource HTTP/1.1

---

HTTP/1.1 200 OK
Content-Profile: urn:example:profile:1;q=0.8,http://example.org/profiles/2;q=0.5
[More headers for this resource]
</pre>
</pre>
</section>
<section id="listprofilehttplink">
<p>
The second way is to issue an <code>GET</code> or <code>HEAD</code> against the resource. In this
case a server implementing
Expand All @@ -400,7 +421,7 @@ <h3>list profiles</h3>
<tr><th>Media type / profile</th><th>urn:example:profile:1</th><th>urn:example:profile:2</th></tr>
<tr><th>text/html</th><td>http://example.org/a/resource.html</td><td>http://example.org/a/resource.html</td></tr>
<tr><th>text/turtle</th><td>http://example.org/a/resource.prof1.ttl</td><td>http://example.org/a/resource.prof2.ttl</td></tr>
<tr><th>application/xml</th><td>http://example.org/a/resource/prof1.xml</td><td>http://example.org/a/resource/prof2.xml</td></tr>
<tr><th>application/xml</th><td>http://example.org/a/resource.prof1.xml</td><td>http://example.org/a/resource.prof2.xml</td></tr>
</table>
<p>
Assuming that a request without an <code>Accept-Profile</code> header per default delivers content conforming to
Expand All @@ -415,6 +436,7 @@ <h3>list profiles</h3>

HTTP/1.1 200 OK
Content-Type: text/turtle
Content-Location: http://example.org/a/resource.prof1.ttl
Content-Profile: urn:example:profile:1
Link: &lt;http://example.org/a/resource.prof1.ttl&gt;; rel="self"; type="text/turtle"; profile="urn:example:profile:1",
&lt;http://example.org/a/resource.prof2.ttl&gt;; rel="alternate"; type="text/turtle"; profile="urn:example:profile:2",
Expand All @@ -424,14 +446,16 @@ <h3>list profiles</h3>
[more response headers]
</pre>
<div class="issue" data-number="501"></div>
</section>
</section>
<section id="getresourcebyprofilehttp">
<h3>get resource by profile</h3>
<p>
Getting a resource representation conforming to a specific profile is done by issuing an HTTP GET
request against the resource and specifying the desired profile URI in an "Accept-Profile" header.
It is possible to specify a range of acceptable profile URIs and also to indicate preferences by using
quality indicators (q-values).
Getting a resource representation conforming to a specific profile is done
by issuing an <code>HTTP GET</code> request against the resource
and specifying the desired profile URI in an <code>Accept-Profile</code> header.
It is possible to specify a range of acceptable profile URIs
and also to indicate preferences by using quality indicators (q-values).
</p>
<pre class="example nohighlight" aria-busy="false" aria-live="polite" title="Requesting a representation conforming to a specific profile using HTTP headers">
GET /a/resource HTTP/1.1
Expand Down Expand Up @@ -462,10 +486,14 @@ <h3>list profiles tokens</h3>
<section id="qsa">
<h2>Query String Arguments</h2>
<div class="issue" data-number="511"></div>
<div class="issue" data-number="516"></div>
<p>
A Query String Argument (QSA) realisation of the Abstract Model is presented here. Unlike the HTTP realisation
which is the subject of an independent document [[PROF-IETF]], this realisation is fully specified here and this
document is considered normative for this realisation. This realisation does not preclude other QSA specifications for profile and content negotiation.
A Query String Argument (QSA) realisation of the <a href="#abstractmodel">Abstract Model</a>
is presented here. Unlike the HTTP realisation
which is the subject of an independent document [[PROF-IETF]],
this realisation is fully specified here
and this document is considered normative for this realisation.
This realisation does not preclude other QSA specifications for profile and content negotiation.
</p>
<p>
A query string is a part of a URI which assigns values to specified parameters. QSAs are commonly used within
Expand All @@ -475,9 +503,11 @@ <h2>Query String Arguments</h2>
<p><strong><em>Key naming</em></strong></p>
<p>
When content negotiation by profile is to take place using QSAs, the <em>request</em>s and <em>response</em>s
of the <a href="#abstractmodel">Abstract Model</a> MUST be implemented however there is some flexibility
in how this may be done: QSA key/value pairs must be implemented but the specific key terms may be changed. In
this realisation, <code>_profile</code> and <code>_mediatype</code> are used to indicate a single or a list of
of the <a href="#abstractmodel">Abstract Model</a> MUST be implemented.
However there is some flexibility in how this may be done:
QSA key/value pairs must be implemented but the specific key terms may be changed.
In this realisation, <code>_profile</code> and <code>_mediatype</code> are used
to indicate a single or a list of
preference-ordered profiles or Media types respectively with profiles or Media Types indicated by either URI or
token.
</p>
Expand All @@ -500,18 +530,18 @@ <h2>Query String Arguments</h2>
</div>
<p><strong><em>Resource URI</em></strong></p>
<p>
Resource URIs for which QSA-based profile negotiation is taking place MUST NOT, themselves be QSA values
Resource URIs for which QSA-based profile negotiation is taking place MUST NOT themselves be QSA values
of other resource URIs in any QSA-based realisation. Such mechanics may be used but must be transparent to the
realisation's <em>client</em> applications.
</p>
<pre class="example nohighlight" aria-busy="false" aria-live="polite" title="Resource URIs must not, themselves, be parameters of other URIs">
For the representation of Resource X, according to Profile Y, in Media Type Z:

NOT ALLOWED:
GET /single/endpoint?resource=http://example.org/resource/X&_profile=Y&_mediatype=Z
GET /single/endpoint?resource=http://example.org/resource/X&amp;_profile=Y&amp;_mediatype=Z HTTP/1.1

ALLOWED:
GET /resource/X?_profile=Y&_mediatype=Z
GET /resource/X?_profile=Y&_mediatype=Z HTTP/1.1
</pre>
<section id="listprofilesqsa">
<h4>list profiles</h4>
Expand All @@ -529,7 +559,7 @@ <h4>list profiles</h4>
communicated in a single URI like thus:
</p>
<pre class="example nohighlight" aria-busy="false" aria-live="polite" title="Requesting a list of profiles for a resource by QSA">
GET /a/resource?_profile=list
GET /a/resource?_profile=list HTTP/1.1
</pre>
<!--
<p><code>RESOURCE_URI?_profile=list</code></p>
Expand All @@ -549,7 +579,7 @@ <h4>list profiles</h4>
</p>
<!--<p><code>RESOURCE_URI?_profile=list&_mediatype=text/html</code></p>-->
<pre class="example nohighlight" aria-busy="false" aria-live="polite" title="Requesting a list of profiles for a resource by QSA in HTML">
GET /a/resource?_profile=list&amp;_mediatype=text/html
GET /a/resource?_profile=list&amp;_mediatype=text/html HTTP/1.1
</pre>
</section>
<section id="getresourcebyprofileqsa">
Expand All @@ -565,12 +595,12 @@ <h4>get resource by profile</h4>
<code>aaa</code>, <code>bbb</code> &amp; <code>ccc</code> we have:
</p>
<pre class="example nohighlight" aria-busy="false" aria-live="polite" title="Requesting a list of profiles for a resource by QSA in HTML">
GET /a/resource?_profile=aaa,bbb,ccc
GET /a/resource?_profile=aaa,bbb,ccc HTTP/1.1
</pre>
<p>
It MAY be possible to use any any combination of profile URIs or tokens for this (e.g. <code>aaa</code>,
<code>http://example.org/profile-x</code>,<code>bbb</code>) however, in this situation, profile URIs containing
commas must escape them.
Servers MAY support any combination of profile URIs or tokens for this
(e.g. <code>aaa,http://example.org/profile-x,bbb</code>).
However, in this situation, profile URIs containing commas must escape them.
</p>
<p>
Similarly, a <em>server</em> implementing multiple Media Type return formats for <em>profile</em> listing SHOULD
Expand All @@ -584,10 +614,10 @@ <h4>get resource by profile</h4>
<h4>list profiles tokens</h4>
<div class="issue" title="To be completed"></div>
</section>
<div class="issue" data-number="516"></div>
</section>
<section id="rest">
<h3>REST</h3>
<div class="issue" title="To be completed"></div>
</section>
</section>
<section id="testsuites" class="informative">
Expand Down

0 comments on commit 3b53c23

Please sign in to comment.