Internet-Draft HTTP Link Hints November 2026
Nottingham Expires 8 May 2027 [Page]
Workgroup:
Network Working Group
Internet-Draft:
draft-ietf-httpapi-link-hint-latest
Published:
Intended Status:
Standards Track
Expires:
Author:
M. Nottingham

HTTP Link Hints

Abstract

This memo specifies "HTTP Link Hints", a mechanism for annotating Web links to HTTP(S) resources with information that otherwise might be discovered by interacting with them.

About This Document

This note is to be removed before publishing as an RFC.

The latest revision of this draft can be found at https://ietf-wg-httpapi.github.io/link-hint/draft-ietf-httpapi-link-hint.html. Status information for this document may be found at https://datatracker.ietf.org/doc/draft-ietf-httpapi-link-hint/.

Discussion of this document takes place on the Building Blocks for HTTP APIs Working Group mailing list (mailto:httpapi@ietf.org), which is archived at https://mailarchive.ietf.org/arch/browse/httpapi/. Subscribe at https://www.ietf.org/mailman/listinfo/httpapi/.

Source for this draft and an issue tracker can be found at https://github.com/ietf-wg-httpapi/link-hint.

Status of This Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."

This Internet-Draft will expire on 8 May 2027.

▲

Table of Contents

1. Introduction

HTTP [HTTP] clients can discover a variety of information about a resource by interacting with it. For example, the methods supported by a resource can be learned by examining the Allow header field in responses from it, and the need for authentication is conveyed with a 401 (Unauthorized) 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 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 [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 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).

Hints are conveyed with a link by its serialisation. This specification defines how for the Link HTTP header field (Section 2.2); other serialisations define their own (Section 2.3).

Finally, these hints are not universally applicable to all links. Section 2.2 of [WEB-LINKING] specifies that target attributes can be defined by link relation types and by serialisations. Therefore, to be used in a given link, these hints need to be explicitly specified by either the link relation type or the serialisation in use (e.g., by referencing this specification).

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; similar to the Allow HTTP header field.

  • Content Model: List of Strings

  • Specification: [this document]

Each String in the List is an HTTP method (Section 9 of [HTTP]); unrecognised values MUST be ignored by recipients.

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.

  • Content Model: List of Strings

  • Specification: [this document]

Each String in the List is a media type (Section 8.3.1 of [HTTP]); unrecognised values MUST be ignored by recipients.

3.3. accept-post

  • Hint Name: accept-post

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

  • Content Model: List of Strings

  • Specification: [this document]

Each String in the List is a media type (Section 8.3.1 of [HTTP]); unrecognised values MUST be ignored by recipients.

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

3.4. accept-patch

  • Hint Name: accept-patch

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

  • Content Model: List of Strings

  • Specification: [this document]

Each String in the List is a media type (Section 8.3.1 of [HTTP]) that identifies an acceptable patch format (see [PATCH]); unrecognised values MUST be ignored by recipients.

When this hint is present, "PATCH" SHOULD be listed in the "allow" hint, when it is present.

3.5. accept-query

  • Hint Name: accept-query

  • Description: Hints the QUERY [QUERY] request format(s) that the target resource can consume; similar to the Accept-Query HTTP response header.

  • Content Model: List of Strings

  • Specification: [this document]

Each String in the List is a media type (Section 8.3.1 of [HTTP]) that identifies an acceptable query format (see [QUERY]); unrecognised values MUST be ignored by recipients.

When this hint is present, "QUERY" SHOULD be listed in the "allow" hint, when it is present.

3.6. accept-ranges

  • Hint Name: accept-ranges

  • Description: Hints the range-unit(s) available for the target resource; similar to the Accept-Ranges HTTP response header [HTTP].

  • Content Model: List of Strings

  • Specification: [this document]

Each String in the List is a range-unit (Section 14.1 of [HTTP]); unrecognised values MUST be ignored by recipients.

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: List of Strings

  • Specification: [this document]

Each String in the List is a preference (Section 2 of [RFC7240]); unrecognised values MUST be ignored by recipients. 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: List of Strings

  • Specification: [this document]

Possible values for each String are "etag" and "last-modified", indicating type of precondition expected; they are compared case-sensitively. Other values MUST be ignored by recipients.

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: List of Strings

  • Specification: [this document]

Each String in the List is an HTTP authentication scheme (Section 11.1 of [HTTP]); unrecognised values MUST be ignored by recipients.

3.10. auth-realms

  • Hint Name: auth-realms

  • Description: Hints the authentication realm(s) available for those schemes that support them in the HTTP Authentication framework Section 11 of [HTTP].

  • Content Model: List of Strings

  • Specification: [this document]

Each String in the List is a realm value (Section 11.5 of [HTTP]); together with the origin of the target resource, it identifies a protection space that the resource is a member of. The hint does not associate realms with authentication schemes; a client learns that from the challenges the target sends. A realm that cannot be represented as a String, because it contains characters outside printable ASCII, is not conveyed.

3.11. status

  • Hint Name: status

  • Description: Hints the status of the target resource.

  • Content Model: String

  • Specification: [this document]

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.

Unrecognised Strings MUST be ignored by recipients.

4. Security Considerations

Link hints are assertions made by the party that publishes a link. That party might not control the target resource, and there is no mechanism for hint verification other than interacting with the resource. Hints are therefore defined as advisory (see Section 1): the behaviour of the target resource always takes precedence, and a client ought to be prepared for any hint to be wrong, whether through staleness, error or malice.

4.1. Authority of Hints

A hint carries the authority of the link's publisher, not of the target. This is most relevant when a link in one origin's representation points at another origin. A client ought not to take actions with side effects, or with security consequences, on the strength of a hint alone.

For example, "auth-schemes" and "auth-realms" could be used to coax a client into offering credentials to a server that has not asked for them. A client ought not to send credentials to a target on the strength of a hint alone, unless they are for a protection space (Section 11.5 of [HTTP]) that the client already associates with that target. For those, "auth-schemes" can save the round trip that a challenge would have cost; for any other, the client waits to be challenged by the target (Section 11 of [HTTP]).

Likewise, a "status" of "gone" or "deprecated" might lead a client or user to avoid a resource that is in fact available, and "allow" or "formats" might lead a user interface to offer operations that the resource will refuse.

Hints are not access control. A server cannot rely on a client having honoured a hint, and has to enforce its policy on every request regardless of what was published. Conversely, the absence of a hint says nothing about what the target allows or requires.

4.2. Hints That Vary By User

As noted in Section 2, hints in a user-specific representation are themselves user-specific. Hints such as "allow" and "precondition-req" reveal what that user is able to do. If a representation containing them can be stored or served to other parties -- for example, by a shared cache, or in a catalogue of links assembled for many users -- those hints can be exposed to, or acted on by, someone they were not generated for. Publishers ought to control caching of such representations (Section 5.2 of [HTTP-CACHING]), and avoid placing user-specific hints in representations that are shared.

Publishers can also disclose through hints what the target would reveal only to authenticated clients, such as the methods or formats of a resource whose existence is otherwise confidential. They ought to consider whether everyone who can see the link is entitled to know what its hints say.

4.3. Stale Hints

A hint can be out of date as soon as it is published. Where a hint and the target's actual behaviour disagree, a client ought to treat the hint as the one that is wrong.

5. IANA Considerations

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

HTTP 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 a String or a List of Strings (Section 2.1); the registration states which.

Hint semantics SHOULD be described in terms of the framework defined in [WEB-LINKING].

New hints are registered using the IETF Review process described in [RFC8126]. Registration of new HTTP link hints is to use the following template:

  • Hint Name: [hint name]

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

  • Content Model: [String or List of Strings]

  • Specification: [reference to specification document]

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

6. References

6.1. Normative References

[HTTP]
Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, Ed., "HTTP Semantics", STD 97, RFC 9110, DOI 10.17487/RFC9110, , <https://www.rfc-editor.org/rfc/rfc9110>.
[HTTP-CACHING]
Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, Ed., "HTTP Caching", STD 98, RFC 9111, DOI 10.17487/RFC9111, , <https://www.rfc-editor.org/rfc/rfc9111>.
[RFC2119]
Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, , <https://www.rfc-editor.org/rfc/rfc2119>.
[RFC7240]
Snell, J., "Prefer Header for HTTP", RFC 7240, DOI 10.17487/RFC7240, , <https://www.rfc-editor.org/rfc/rfc7240>.
[RFC8174]
Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, , <https://www.rfc-editor.org/rfc/rfc8174>.
[WEB-LINKING]
Nottingham, M., "Web Linking", RFC 8288, DOI 10.17487/RFC8288, , <https://www.rfc-editor.org/rfc/rfc8288>.

6.2. Informative References

[PATCH]
Dusseault, L. and J. Snell, "PATCH Method for HTTP", RFC 5789, DOI 10.17487/RFC5789, , <https://www.rfc-editor.org/rfc/rfc5789>.
[QUERY]
Reschke, J., Snell, J.M., and M. Bishop, "The HTTP QUERY Method", RFC 10008, DOI 10.17487/RFC10008, , <https://www.rfc-editor.org/rfc/rfc10008>.
[RFC6585]
Nottingham, M. and R. Fielding, "Additional HTTP Status Codes", RFC 6585, DOI 10.17487/RFC6585, , <https://www.rfc-editor.org/rfc/rfc6585>.
[RFC8126]
Cotton, M., Leiba, B., and T. Narten, "Guidelines for Writing an IANA Considerations Section in RFCs", BCP 26, RFC 8126, DOI 10.17487/RFC8126, , <https://www.rfc-editor.org/rfc/rfc8126>.
[RFC9264]
Wilde, E. and H. Van de Sompel, "Linkset: Media Types and a Link Relation Type for Link Sets", RFC 9264, DOI 10.17487/RFC9264, , <https://www.rfc-editor.org/rfc/rfc9264>.

Appendix A. Acknowledgements

Thanks to Jan Algermissen, Mike Amundsen, Bill Burke, Graham Klyne, Leif Hedstrom, Jeni Tennison, Erik Wilde and Jorge Williams for their suggestions and feedback.

Author's Address

Mark Nottingham