Update references, etc.

Author: mnot

draft-ietf-httpapi-link-hint.md

@@ -29,6 +29,12 @@ author:
     uri: https://www.mnot.net/
 
 normative:
+  HTTP: RFC9110
+  HTTP-CACHING: RFC9111
+  WEB-LINKING: RFC8288
+  JSON: RFC8259
+  URI: RFC3986
+
 
 --- abstract
 
@@ -39,21 +45,21 @@ This memo specifies "HTTP Link Hints", a mechanism for annotating Web links to H
 
 # Introduction
 
-HTTP {{!RFC7230}} clients can discover a variety of information about a resource by interacting with it. For example, the methods supported can be learned through the Allow response header field, and the need for authentication is conveyed with a 401 Authentication Required status code.
+HTTP {{HTTP}} clients can discover a variety of information about a resource by interacting with it. For example, the methods supported can be learned through the Allow response header field, and the need for authentication is conveyed with a 401 (Authentication Required) status code.
 
-Often, it can be beneficial to know this information before interacting with the resource; not only can such knowledge save time (through reduced round trips), but it can also affect the choices available to the code or user driving the interaction.
+Often, it can be beneficial to know this information before interacting with the resource; not only can such knowledge save time (through reduced round trips), but it can also influence the choices made by the code or user driving the interaction.
 
 For example, a user interface that presents the data from an HTTP-based API might need to know which resources the user has write access to, so that it can present the appropriate interface.
 
-This specification defines a vocabulary of "HTTP link hints" that allow such metadata about HTTP resources to be attached to Web links {{!RFC8288}}, thereby making it available before the link is followed. It also establishes a registry for future hints.
+This specification defines a vocabulary of "HTTP link hints" that allow such metadata about HTTP resources to be attached to Web links {{WEB-LINKING}}, thereby making it available before the link is followed. It also establishes a registry for future hints.
 
 Hints are just that -- they are not a "contract", and are to only be taken as advisory. The runtime behaviour of the resource always overrides hinted information.
 
-For example, a client might receive a hint that the PUT method is allowed on all "widget" resources. This means that generally, the client can PUT to them, but a specific resource might reject a PUT based upon access control or other considerations.
+For example, a client might receive a hint that the PUT method is allowed on all "widget" resources. This means that generally, the client can send a PUT to them, but a specific resource might reject a PUT based upon access control or other considerations.
 
 More fine-grained information might also be gathered by interacting with the resource (e.g., via a GET), or by another resource "containing" it (such as a "widgets" collection) or describing it (e.g., one linked to it with a "describedby" link relation).
 
-There is not a single way to carry hints in a link; rather, it is expected that this will be done by individual link serialisations (see {{!RFC8288}}, Section 3.4.1). However, {{link_header}} does recommend how to include link hints in the existing Link HTTP header field.
+There is not a single way to carry hints in a link; rather, it is expected that this will be done by individual link serialisations (see {{Section 3.4.1 of WEB-LINKING}}). However, {{link_header}} does recommend how to include link hints in the existing Link header field.
 
 
 ## Notational Conventions
@@ -63,9 +69,9 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "S
 
 # HTTP Link Hints {#link_hints}
 
-A HTTP link hint is a (key, value) tuple that describes the target resource of a Web link {{!RFC8288}}, or the link itself. The value's canonical form is a JSON {{!RFC8259}} data structure specific to that hint.
+A HTTP link hint is a (key, value) tuple that describes the target resource of a Web link {{WEB-LINKING}}, or the link itself. The value's canonical form is a JSON {{JSON}} data structure specific to that hint.
 
-Typically, link hints are serialised in links as target attributes ({{!RFC8288}}, Section 3.4.1).
+Typically, link hints are serialised in links as target attributes ({{Section 3.4.1 of WEB-LINKING}}).
 
 In JSON-based formats, this can be achieved by simply serialising link hints as an object; for example:
 
@@ -87,9 +93,9 @@ In JSON-based formats, this can be achieved by simply serialising link hints as
 }
 ~~~
 
-In other link formats, this requires a mapping from the canonical JSON data model. One such mapping is described in {{link_header}} for the Link HTTP header field.
+In other link formats, this requires a mapping from the canonical JSON data model into the constraints of that format. One such mapping is described in {{link_header}} for the Link HTTP header field.
 
-The information in a link hint SHOULD NOT be considered valid for longer than the freshness lifetime ({{!RFC7234}}, Section 4.2) of the representation that the link occurred within, and in some cases, it might be valid for a considerably shorter period.
+The information in a link hint SHOULD NOT be considered valid for longer than the freshness lifetime ({{Section 4.2 of HTTP-CACHING}}) of the representation that the link occurred within, and in some cases, it might be valid for a considerably shorter period.
 
 Likewise, the information in a link hint is specific to the link it is attached to. This means that if a representation is specific to a particular user, the hints on links in that representation are also specific to that user.
 
@@ -104,7 +110,7 @@ Likewise, the information in a link hint is specific to the link it is attached
 * Content Model: array (of strings)
 * Specification: \[this document]
 
-Content MUST be an array of strings, containing HTTP methods ({{!RFC7231}}, Section 4).
+Content MUST be an array of strings, containing HTTP methods ({{Section 9 of HTTP}}).
 
 ## formats
 
@@ -113,9 +119,9 @@ Content MUST be an array of strings, containing HTTP methods ({{!RFC7231}}, Sect
 * Content Model: object
 * Specification: \[this document]
 
-Content MUST be an object, whose keys are media types ({{!RFC7231}}, Section 3.1.1.1), and values are objects.
+Content MUST be an object, whose keys are media types ({{Section 8.3.1 of HTTP}}), and values are objects.
 
-The object MAY have a "links" member, whose value is an object representing links (in the sense of {{!RFC8288}}) whose context is any document that uses that format. Generally, this will be schema or profile ({{?RFC6906}}) information. The "links" member has the same format as the "links" hint.
+The object MAY have a "links" member, whose value is an object representing links (in the sense of {{WEB-LINKING}}) whose context is any document that uses that format. Generally, this will be schema or profile ({{?RFC6906}}) information. The "links" member has the same format as the "links" hint.
 
 Furthermore, the object MAY have a "deprecated" member, whose value is either true or false, indicating whether support for the format might be removed in the near future.
 
@@ -129,9 +135,9 @@ All other members of the object are under control of the corresponding media typ
 * Content Model: object
 * Specification: \[this document]
 
-The "links" hint contains links (in the sense of {{!RFC8288}}) whose context is the hinted target resource, which are stable for the lifetime of the hint.
+The "links" hint contains links (in the sense of {{WEB-LINKING}}) whose context is the hinted target resource, which are stable for the lifetime of the hint.
 
-Content MUST be an object, whose member names are link relations ({{!RFC8288}}) and values are objects that MUST have an "href" member whose value is a URI-reference ({{!RFC3986}}, using the original link as the base for resolution) for the link hint's target resource, and MAY itself contain link hints, serialised as the value for a "hints" member.
+Content MUST be an object, whose member names are link relations ({{WEB-LINKING}}) and values are objects that MUST have an "href" member whose value is a URI-reference ({{URI}}, using the original link as the base for resolution) for the link hint's target resource, and MAY itself contain link hints, serialised as the value for a "hints" member.
 
 For example:
 
@@ -166,18 +172,18 @@ When this hint is present, "POST" SHOULD be listed in the "allow" hint.
 * Content Model: array (of strings)
 * Specification: \[this document]
 
-Content MUST be an array of strings, containing media types ({{!RFC7231}}, Section 3.1.1.1).
+Content MUST be an array of strings, containing media types ({{Section 8.3.1 of HTTP}}) that identify the acceptable patch formats.
 
 When this hint is present, "PATCH" SHOULD be listed in the "allow" hint.
 
 ## accept-ranges
 
 * Hint Name: accept-ranges
-* Description: Hints the range-specifier(s) available for the target resource; equivalent to the Accept-Ranges HTTP response header {{!RFC7233}}.
+* Description: Hints the range-specifier(s) available for the target resource; equivalent to the Accept-Ranges HTTP response header {{HTTP}}.
 * Content Model: array (of strings)
 * Specification: \[this document]
 
-Content MUST be an array of strings, containing HTTP range-specifiers ({{!RFC7233}}, Section 3.1).
+Content MUST be an array of strings, containing HTTP ranges-specifiers ({{Section 14.1.1 of HTTP}}).
 
 ## accept-prefer
 
@@ -186,12 +192,12 @@ Content MUST be an array of strings, containing HTTP range-specifiers ({{!RFC723
 * Content Model: array (of strings)
 * Specification: \[this document]
 
-Content MUST be an array of strings, contain preferences ({{!RFC7240}}, Section 2). Note that, by its nature, a preference can be ignored by the server.
+Content MUST be an array of strings, contain preferences ({{Section 2 of RFC7240}}). Note that, by its nature, a preference can be ignored by the server.
 
 ## precondition-req
 
 * Hint Name: precondition-req
-* Description: Hints that the target resource requires state-changing requests (e.g., PUT, PATCH) to include a precondition, as per {{!RFC7232}}, to avoid conflicts due to concurrent updates.
+* Description: Hints that the target resource requires state-changing requests (e.g., PUT, PATCH) to include a precondition, as per {{Section 13.1 of HTTP}}, to avoid conflicts due to concurrent updates.
 * Content Model: array (of strings)
 * Specification: \[this document]
 
@@ -202,11 +208,11 @@ See also the 428 Precondition Required status code ({{!RFC6585}}).
 ## auth-schemes
 
 * Hint Name: auth-schemes
-* Description: Hints that the target resource requires authentication using the HTTP Authentication Framework {{!RFC7235}}.
+* Description: Hints that the target resource requires authentication using the HTTP Authentication framework {{Section 11 of HTTP}}.
 * Content Model: array (of objects)
 * Specification: \[this document]
 
-Content MUST be an array of objects, each with a "scheme" member containing a string that corresponds to a HTTP authentication scheme ({{!RFC7235}}), and optionally a "realms" member containing an array of zero to many strings that identify protection spaces that the resource is a member of.
+Content MUST be an array of objects, each with a "scheme" member containing a string that corresponds to a HTTP authentication scheme ({{Section 11.1 of HTTP}}), and optionally a "realms" member containing an array of zero to many strings that identify protection spaces that the resource is a member of.
 
 For example:
 
@@ -231,7 +237,7 @@ For example:
 Content MUST be a string; possible values are:
 
 * "deprecated" - indicates that use of the resource is not recommended, but it is still available.
-* "gone" - indicates that the resource is no longer available; i.e., it will return a 410 Gone HTTP status code if accessed.
+* "gone" - indicates that the resource is no longer available; i.e., it will return a 410 (Gone) HTTP status code if accessed.
 
 
 
@@ -250,9 +256,9 @@ Link hints are generic; that is, they are potentially applicable to any HTTP res
 
 Hint names MUST be composed of the lowercase letters (a-z), digits (0-9), underscores ("_") and hyphens ("-"), and MUST begin with a lowercase letter.
 
-Hint content MUST be described in terms of JSON values ({{!RFC8259}}, Section 3).
+Hint content MUST be described in terms of JSON values ({{Section 3 of JSON}}).
 
-Hint semantics SHOULD be described in terms of the framework defined in {{!RFC8288}}.
+Hint semantics SHOULD be described in terms of the framework defined in {{WEB-LINKING}}.
 
 New hints are registered using the Expert Review process described in {{?RFC8126}} to enforce the criteria above. Requests for registration of new resource hints are to use the following template:
 
@@ -268,9 +274,9 @@ Initial registrations are enumerated in {{hints}}. The "rel", "rev", "hreflang",
 
 # Representing Link Hints in Link Headers {#link_header}
 
-A link hint can be represented in a Link header ({{!RFC8288}}, Section 3) as a link-extension.
+A link hint can be represented in a Link header ({{Section 3 of WEB-LINKING}}) as a link-extension.
 
-When doing so, the JSON of the hint's content SHOULD be normalised to reduce extraneous spaces (%x20), and MUST NOT contain horizontal tabs (%x09), line feeds (%x0A) or carriage returns (%x0D). When they are part of a string value, these characters MUST be escaped as described in {{!RFC8259}} Section 7; otherwise, they MUST be discarded.
+When doing so, the JSON of the hint's content SHOULD be normalised to reduce extraneous spaces (%x20), and MUST NOT contain horizontal tabs (%x09), line feeds (%x0A) or carriage returns (%x0D). When they are part of a string value, these characters MUST be escaped as described in {{Section 7 of JSON}}; otherwise, they MUST be discarded.
 
 Furthermore, if the content is an array or an object, the surrounding delimiters MUST be removed before serialisation. In other words, the outermost object or array is represented without the braces ("{}") or brackets ("[]") respectively, but this does not apply to inner objects or arrays.