Draft: draft-ietf-httpapi-linkset-03

Commentary: thanks a lot , that was very helpful ! 
 i am wondering if referencing drafts does n't automatically hold up this draft from progressing until the references are stable RFCs ? not sure what the official policy is , but at least so far my personal strategy has been to only reference drafts when there 's no existing stable reference . 
 The http - core drafts are in IETF Last Call . They do change terminology a bit from RFC 723x , and you 'll have to update at some point in the future anyway ( unless you manage to beat those drafts in getting into the RFC Publication Queue ) . 
 fair point . i 'll leave this issue open for now , but i think it can be considered editorial .
Paragraph (version A):
Resources on the Web often use typed Web Links RFC8288, either
embedded in resource representations, for example using the <link>
element for HTML documents, or conveyed in the HTTP "Link" header for
documents of any media type.  In some cases, however, providing links
in this manner is impractical or impossible and delivering a set of
links as a stand-alone document is preferable.
Paragraph (version B):
Resources on the Web often use typed Web Links RFC8288, either
embedded in resource representations, for example using the <link>
element for HTML documents, or conveyed in the HTTP "Link" header
field for documents of any media type.  In some cases, however,
providing links in this manner is impractical or impossible and
delivering a set of links as a stand-alone document is preferable.
Paragraph (version A):
In the examples provided in this document, links in the HTTP "Link"
header are shown on separate lines in order to improve readability.
Note, however, that as per Section 3.2 of RFC7230, line breaks are
not allowed in values for HTTP headers; only whitespaces and tabs are
supported as seperators.
Paragraph (version B):
In the examples provided in this document, links in the HTTP "Link"
header field are shown on separate lines in order to improve
readability.  Note, however, that as per Section 5.5 of I-D.ietf-
httpbis-semantics, line breaks are not allowed in values for HTTP
fields; only whitespaces and tabs are supported as seperators.
Paragraph (version A):
For all scenarios, links could be provided by means of a stand-alone
document that is formatted according to the JSON-based serialization,
the serialization aligned with the HTTP "Link" header format, or
both.  The former serialization is motivated by the widespread use of
JSON and related tools, which suggests that handling sets of links
expressed as JSON documents should be attractive to developers.  The
latter serialization is provided for compatibility with the existing
serialization used in the HTTP "Link" header and to allow reuse of
tools created to handle it.
Paragraph (version B):
For all scenarios, links could be provided by means of a stand-alone
document that is formatted according to the JSON-based serialization,
the serialization aligned with the HTTP "Link" field format, or both.
The former serialization is motivated by the widespread use of JSON
and related tools, which suggests that handling sets of links
expressed as JSON documents should be attractive to developers.  The
latter serialization is provided for compatibility with the existing
serialization used in the HTTP "Link" field and to allow reuse of
tools created to handle it.
Paragraph (version A):
In some cases, it is not straightforward to write links to the HTTP
"Link" header field from an application.  This can, for example, be
the case because not all required link information is available to
the application or because the application does not have the
capability to directly write HTTP headers.  In such cases, providing
links by means of a standalone document can be a solution.  Making
the resource that provides these links discoverable can be achieved
by means of a typed link.
Paragraph (version B):
In some cases, it is not straightforward to write links to the HTTP
"Link" header field from an application.  This can, for example, be
the case because not all required link information is available to
the application or because the application does not have the
capability to directly write HTTP fields.  In such cases, providing
links by means of a standalone document can be a solution.  Making
the resource that provides these links discoverable can be achieved
by means of a typed link.
Paragraph (version A):
When conveying links in an HTTP "Link" header field, it is possible
for the size of the HTTP response header to become unpredictable.
This can be the case when links are determined dynamically dependent
on a range of contextual factors.  It is possible to statically
configure a web server to correctly handle large HTTP response
headers by specifying an upper bound for their size.  But when the
number of links is unpredictable, estimating a reliable upper bound
is challenging.
Paragraph (version A):
HTTP RFC7231 defines error codes related to excess communication by
the user agent ("413 Request Entity Too Large" and "414 Request-URI
Too Long"), but no specific error codes are defined to indicate that
response header content exceeds the upper bound that can be handled
by the server, and thus it has been truncated.  As a result,
applications take counter measures aimed at controlling the size of
the HTTP "Link" header field, for example by limiting the links they
provide to those with select relation types, thereby limiting the
value of the HTTP "Link" header field to clients.  Providing links by
means of a standalone document overcomes challenges related to the
unpredictable nature of the size of HTTP "Link" header fields.
Paragraph (version B):
When conveying links in an HTTP "Link" header field, it is possible
for the size of the HTTP response fields to become unpredictable.
This can be the case when links are determined dynamically dependent
on a range of contextual factors.  It is possible to statically
configure a web server to correctly handle large HTTP response fields
by specifying an upper bound for their size.  But when the number of
links is unpredictable, estimating a reliable upper bound is
challenging.
Paragraph (version B):
Section 15 of HTTP I-D.ietf-httpbis-semantics defines error codes
related to excess communication by the user agent ("413 Request
Entity Too Large" and "414 Request-URI Too Long"), but no specific
error codes are defined to indicate that response field content
exceeds the upper bound that can be handled by the server, and thus
it has been truncated.  As a result, applications take counter
measures aimed at controlling the size of the HTTP "Link" header
field, for example by limiting the links they provide to those with
select relation types, thereby limiting the value of the HTTP "Link"
header field to clients.  Providing links by means of a standalone
document overcomes challenges related to the unpredictable nature of
the size of HTTP "Link" header fields.
Paragraph (version A):
It should be noted that the "application/linkset" format specified
here is different than the "application/link-format" format specified
in RFC6690 in that the former fully matches the payload of the HTTP
"Link" header as defined in Section 3 of RFC8288, whereas the latter
introduces constraints on that definition to meet requirements for
Constrained RESTful Environments.
Paragraph (version B):
It should be noted that the "application/linkset" format specified
here is different than the "application/link-format" format specified
in RFC6690 in that the former fully matches the payload of the HTTP
"Link" header field as defined in Section 3 of RFC8288, whereas the
latter introduces constraints on that definition to meet requirements
for Constrained RESTful Environments.
Paragraph (version A):
This limitation of the JSON format allows to unambiguously round trip
between links provided in the HTTP "Link" header, sets of links
serialized according to the "application/linkset" format, and sets of
links serialized according to the "application/linkset+json" format.
Paragraph (version B):
This limitation of the JSON format allows to unambiguously round trip
between links provided in the HTTP "Link" header field, sets of links
serialized according to the "application/linkset" format, and sets of
links serialized according to the "application/linkset+json" format.
Paragraph (version A):
A link with the "linkset" relation type MAY be provided in the header
and/or the body of a resource's representation.  It may also be
discovered by other means, such as through client-side information.
Paragraph (version B):
A link with the "linkset" relation type MAY be provided in the header
field and/or the body of a resource's representation.  It may also be
discovered by other means, such as through client-side information.
Paragraph (version A):
Response1.1 shows the response to the GET request of Request1.  The
response contains a Content-Type header specifying that the media
type of the response is "application/linkset".  A set of links,
revealing authorship and versioning related to resource
<https://example.org/resource1>, is provided in the response body.
The HTTP "Link" header indicates the availability of an alternate
representation of the set of links using media type "application/
linkset+json".
Paragraph (version A):
Request4 shows the client issuing an HTTP GET request against
<https://example.org/links/resource1>.  In the request, the client
uses an "Accept" header to indicate it prefers a response in the
"application/linkset+json" format.
Paragraph (version B):
Response1.1 shows the response to the GET request of Request1.  The
response contains a Content-Type header field specifying that the
media type of the response is "application/linkset".  A set of links,
revealing authorship and versioning related to resource
<https://example.org/resource1>, is provided in the response body.
The HTTP "Link" header field indicates the availability of an
alternate representation of the set of links using media type
"application/linkset+json".
Paragraph (version B):
Request4 shows the client issuing an HTTP GET request against
<https://example.org/links/resource1>.  In the request, the client
uses an "Accept" header field to indicate it prefers a response in
the "application/linkset+json" format.
Paragraph (version A):
Response3.1 shows the response to the HEAD request of Request3.  The
response contains an HTTP "Link" header with a link that has the
"linkset" relation type.  It indicates that a set of links is
provided by resource <https://example.org/links/resource1>, which
provides a representation with media type "application/linkset+json".
Paragraph (version B):
Response3.1 shows the response to the HEAD request of Request3.  The
response contains an HTTP "Link" header field with a link that has
the "linkset" relation type.  It indicates that a set of links is
provided by resource <https://example.org/links/resource1>, which
provides a representation with media type "application/linkset+json".
Paragraph (version A):
Encoding considerations: Linksets are encoded according to the
definition of RFC8288.  The encoding of RFC8288 is based on the
general encoding rules of RFC7230, with the addition of allowing
indicating character encoding and language for specific parameters
as defined by RFC8187.
Paragraph (version A):
Interoperability considerations: The interoperability
considerations of RFC7230 apply.
Paragraph (version B):
Encoding considerations: Linksets are encoded according to the
definition of RFC8288.  The encoding of RFC8288 is based on the
general encoding rules of I-D.ietf-httpbis-semantics, with the
addition of allowing indicating character encoding and language
for specific parameters as defined by RFC8187.
Paragraph (version B):
Interoperability considerations: The interoperability
considerations of I-D.ietf-httpbis-semantics apply.