HTTP Link Hints

1.1. Notational Conventions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶

3.1. allow

• Hint Name: allow¶

• Description: Hints the HTTP methods that can be used to interact with the target resource; equivalent to the Allow HTTP response header.¶

• Content Model: array (of strings)¶

• Specification: [this document]¶

Content MUST be an array of strings, containing HTTP methods (Section 9 of [HTTP]).¶

3.2. formats

• Hint Name: formats¶

• Description: Hints the representation type(s) that the target resource can produce and consume, using the GET and PUT (if allowed) methods respectively.¶

• Content Model: object¶

• Specification: [this document]¶

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 [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.¶

All other members of the object are under control of the corresponding media type's definition.¶

3.3. links

• Hint Name: links¶

• Description: Hints at links whose context is the target resource.¶

• Content Model: object¶

• Specification: [this document]¶

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 ([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:¶

"links": {
  "edit-form": {
    "href": "./edit",
    "hints": {
      "formats": {
        "application/json": {}
      }
    }
  }
}

3.4. accept-post

• Hint Name: accept-post¶

• Description: Hints the POST request format(s) that the target resource can consume.¶

• Content Model: object¶

• Specification: [this document]¶

Content MUST be an object, with the same constraints as for "formats".¶

When this hint is present, "POST" SHOULD be listed in the "allow" hint.¶

3.5. accept-patch

• Hint Name: accept-patch¶

• Description: Hints the PATCH [RFC5789] request format(s) that the target resource can consume; equivalent to the Accept-Patch HTTP response header.¶

• Content Model: array (of strings)¶

• Specification: [this document]¶

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.¶

3.6. 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 [HTTP].¶

• Content Model: array (of strings)¶

• Specification: [this document]¶

Content MUST be an array of strings, containing HTTP ranges-specifiers (Section 14.1.1 of [HTTP]).¶

3.7. accept-prefer

• Hint Name: accept-prefer¶

• Description: Hints the preference(s) [RFC7240] that the target resource understands (and might act upon) in requests.¶

• Content Model: array (of strings)¶

• Specification: [this document]¶

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.¶

3.8. 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 Section 13.1 of [HTTP], to avoid conflicts due to concurrent updates.¶

• Content Model: array (of strings)¶

• Specification: [this document]¶

Content MUST be an array of strings, with possible values "etag" and "last-modified" indicating type of precondition expected.¶

See also the 428 Precondition Required status code ([RFC6585]).¶

3.9. auth-schemes

• Hint Name: auth-schemes¶

• 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 (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:¶

  {
    "auth-req": [
      {
        "scheme": "Basic",
        "realms": ["private"]
      }
    ]
  }

3.10. status

• Hint Name: status¶

• Description: Hints the status of the target resource.¶

• Content Model: string¶

• Specification: [this document]¶

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.¶

5.1. HTTP Link Hint Registry

This specification defines the HTTP Link Hint Registry. See Section 2 for a general description of the function of link hints.¶

Link hints are generic; that is, they are potentially applicable to any HTTP resource, not specific to one application of HTTP, nor to one particular format. Generally, they ought to be information that would otherwise be discoverable by interacting with the resource.¶

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 (Section 3 of [JSON]).¶

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:¶

• Hint Name: [hint name]¶

• Description: [a short description of the hint's semantics]¶

• Content Model: [valid JSON value types; see RFC627 Section 2.1]¶

• Specification: [reference to specification document]¶

Initial registrations are enumerated in Section 3. The "rel", "rev", "hreflang", "media", "title", and "type" hint names are reserved, so as to avoid potential clashes with link serialisations.¶