draft-ietf-httpapi-link-template-02.unpg.txt | draft-ietf-httpapi-link-template-latest.txt | |||
---|---|---|---|---|
Building Blocks for HTTP APIs M. Nottingham | Building Blocks for HTTP APIs M. Nottingham | |||
Internet-Draft February 1, 2023 | Internet-Draft September 03, 2023 | |||
Intended status: Standards Track | Intended status: Standards Track | |||
Expires: August 5, 2023 | Expires: March 6, 2024 | |||
The Link-Template HTTP Header Field | The Link-Template HTTP Header Field | |||
draft-ietf-httpapi-link-template-02 | draft-ietf-httpapi-link-template-latest | |||
Abstract | Abstract | |||
This specification defines the Link-Template HTTP header field, | This specification defines the Link-Template HTTP header field, | |||
providing a means for describing the structure of a link between two | providing a means for describing the structure of a link between two | |||
resources, so that new links can be generated. | resources, so that new links can be generated. | |||
About This Document | About This Document | |||
This note is to be removed before publishing as an RFC. | This note is to be removed before publishing as an RFC. | |||
skipping to change at line 48 ¶ | skipping to change at page 2, line 4 ¶ | |||
Internet-Drafts are working documents of the Internet Engineering | Internet-Drafts are working documents of the Internet Engineering | |||
Task Force (IETF). Note that other groups may also distribute | Task Force (IETF). Note that other groups may also distribute | |||
working documents as Internet-Drafts. The list of current Internet- | working documents as Internet-Drafts. The list of current Internet- | |||
Drafts is at https://datatracker.ietf.org/drafts/current/. | Drafts is at https://datatracker.ietf.org/drafts/current/. | |||
Internet-Drafts are draft documents valid for a maximum of six months | Internet-Drafts are draft documents valid for a maximum of six months | |||
and may be updated, replaced, or obsoleted by other documents at any | and may be updated, replaced, or obsoleted by other documents at any | |||
time. It is inappropriate to use Internet-Drafts as reference | time. It is inappropriate to use Internet-Drafts as reference | |||
material or to cite them other than as "work in progress." | material or to cite them other than as "work in progress." | |||
This Internet-Draft will expire on March 6, 2024. | ||||
This Internet-Draft will expire on August 5, 2023. | ||||
Copyright Notice | Copyright Notice | |||
Copyright (c) 2023 IETF Trust and the persons identified as the | Copyright (c) 2023 IETF Trust and the persons identified as the | |||
document authors. All rights reserved. | document authors. All rights reserved. | |||
This document is subject to BCP 78 and the IETF Trust's Legal | This document is subject to BCP 78 and the IETF Trust's Legal | |||
Provisions Relating to IETF Documents | Provisions Relating to IETF Documents | |||
(https://trustee.ietf.org/license-info) in effect on the date of | (https://trustee.ietf.org/license-info) in effect on the date of | |||
publication of this document. Please review these documents | publication of this document. Please review these documents | |||
carefully, as they describe your rights and restrictions with respect | carefully, as they describe your rights and restrictions with respect | |||
to this document. Code Components extracted from this document must | to this document. Code Components extracted from this document must | |||
include Simplified BSD License text as described in Section 4.e of | include Simplified BSD License text as described in Section 4.e of | |||
the Trust Legal Provisions and are provided without warranty as | the Trust Legal Provisions and are provided without warranty as | |||
described in the Simplified BSD License. | described in the Simplified BSD License. | |||
Table of Contents | Table of Contents | |||
1. Introduction | 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 | |||
1.1. Notational Conventions | 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 2 | |||
2. The Link-Template Header Field | 2. The Link-Template Header Field . . . . . . . . . . . . . . . 3 | |||
2.1. The 'var-base' parameter | 2.1. The 'var-base' parameter . . . . . . . . . . . . . . . . 4 | |||
3. Security Considerations | 3. Security Considerations . . . . . . . . . . . . . . . . . . . 4 | |||
4. IANA Considerations | 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 5 | |||
5. Normative References | 5. Normative References . . . . . . . . . . . . . . . . . . . . 5 | |||
Author's Address | Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 6 | |||
1. Introduction | 1. Introduction | |||
[URI-TEMPLATE] defines a syntax for templates that, when expanded | [URI-TEMPLATE] defines a syntax for templates that, when expanded | |||
using a set of variables, results in a URI [URI]. | using a set of variables, results in a URI [URI]. | |||
This specification defines a HTTP header field [HTTP] for conveying | This specification defines a HTTP header field [HTTP] for conveying | |||
templates for links in the headers of a HTTP message. It is | templates for links in the headers of a HTTP message. It is | |||
complimentary to the Link header field defined in Section 3 of | complimentary to the Link header field defined in Section 3 of | |||
[WEB-LINKING], which carries links directly. | [WEB-LINKING], which carries links directly. | |||
skipping to change at line 111 ¶ | skipping to change at page 3, line 18 ¶ | |||
[STRUCTURED-FIELDS] that serializes one or more links into HTTP | [STRUCTURED-FIELDS] that serializes one or more links into HTTP | |||
message metadata. It is semantically equivalent to the Link header | message metadata. It is semantically equivalent to the Link header | |||
field defined in Section 3 of [WEB-LINKING], except that it uses URI | field defined in Section 3 of [WEB-LINKING], except that it uses URI | |||
Templates [URI-TEMPLATE] to convey the structure of links. | Templates [URI-TEMPLATE] to convey the structure of links. | |||
Its value is a List of Strings. Each String is a URI Template, and | Its value is a List of Strings. Each String is a URI Template, and | |||
Parameters on it carry associated metadata. | Parameters on it carry associated metadata. | |||
For example: | For example: | |||
Link-Template: "/{username}"; rel="https://example.org/rel/user" | Link-Template: "/{username}"; rel="item" | |||
indicates that a resource with the relation type | ||||
"https://example.org/rel/user" can be found by expanding the | ||||
"username" variable into the template given. | ||||
The target for the link (as defined in Section 2 of [WEB-LINKING]) is | ||||
the result of expanding the URI Template [URI-TEMPLATE] (being | ||||
converted to an absolute URI after expansion, if necessary). | ||||
The context, relation type and target attributes for the link are | indicates that a resource with the relation type "item" for a given | |||
determined as defined for the Link header field in Section 3 of | "username" can be found by expanding the "username" variable into the | |||
[WEB-LINKING]. | template given. | |||
Parameters on a templated link have identical semantics to those of a | The link target (as defined in Section 2 of [WEB-LINKING]) is the | |||
Link header field. This includes (but is not limited to) the use of | result of expanding the URI Template [URI-TEMPLATE] (being converted | |||
the "rel" parameter to convey the relation type, the "anchor" | to an absolute URI after expansion, if necessary). | |||
parameter to modify the context IRI, and so on. Parameter values | ||||
MUST be Strings. | ||||
Likewise, the requirements for parameters on templated links are the | The link context and link relation type for the link (as defined in | |||
same as those for a Link header field. | Section 2 of [WEB-LINKING]) are conveyed using the "anchor" and "rel" | |||
Parameters, as they are for the Link header field in Section 3 of | ||||
[WEB-LINKING]. Their values MUST be Strings. | ||||
However, the "anchor" parameter MAY contain a URI Template. For | However, the "anchor" Parameter MAY contain a URI Template. For | |||
example: | example: | |||
Link-Template: </books/{book_id}/author>; | Link-Template: "/books/{book_id}/author"; | |||
rel="author" anchor="#{book_id}" | rel="author"; anchor="#{book_id}" | |||
Here, the link to the author for a particular book in a list of books | Here, the link to the author for a particular book in a list of books | |||
can be found by following the link template. | can be found by following the link template. | |||
Implementations MUST support all levels of template defined by | ||||
[URI-TEMPLATE] in both the rel and anchor parameters. | ||||
This specification defines additional semantics for the "var-base" | This specification defines additional semantics for the "var-base" | |||
parameter on templated links; see below. | Parameter on templated links; see below. | |||
The link's target attributes (as defined in Section 2.2 of | ||||
[WEB-LINKING]) are conveyed using other Parameters, in a manner | ||||
similar to the Link header field. These Parameter values MUST be | ||||
Strings. Note that some target attribute names will not serialise as | ||||
Structure Field Parameter keys (see Section 3.1.2 of | ||||
[STRUCTURED-FIELDS]). | ||||
Implementations MUST support all levels of template defined by | ||||
[URI-TEMPLATE] in the link String and the anchor Parameter. | ||||
2.1. The 'var-base' parameter | 2.1. The 'var-base' parameter | |||
When a templated link has a 'var-base' parameter, its value conveys a | When a templated link has a 'var-base' parameter, its value conveys a | |||
URI-reference that is used as a base URI for the variable names in | URI-reference that is used as a base URI for the variable names in | |||
the URI template. This allows template variables to be globally | the URI template. This allows template variables to be globally | |||
identified, rather than specific to the context of use. | identified, rather than specific to the context of use. | |||
Dereferencing the URI for a particular variable might lead to more | Dereferencing the URI for a particular variable might lead to more | |||
information about the syntax or semantics of that variable; | information about the syntax or semantics of that variable; | |||
specification of particular formats for this information is out of | specification of particular formats for this information is out of | |||
scope for this document. | scope for this document. | |||
To determine the URI for a given variable, the value given is used as | To determine the URI for a given variable, the value given is used as | |||
a base URI in reference resolution (as specified in [URI]). If the | a base URI in reference resolution (as specified in [URI]). If the | |||
resulting URI is still relative, the context of the link is used as | resulting URI is still relative, the context of the link is used as | |||
the base URI in a further resolution; see [WEB-LINKING]. | the base URI in a further resolution; see [WEB-LINKING]. | |||
For example: | For example: | |||
Link-Template: "/widgets/{widget_id}" | Link-Template: "/widgets/{widget_id}"; | |||
rel="https://example.org/rel/widget"; | rel="https://example.org/rel/widget"; | |||
var-base="https://example.org/vars/" | var-base="https://example.org/vars/" | |||
indicates that a resource with the relation type | indicates that a resource with the relation type | |||
"https://example.org/rel/widget" can be found by expanding the | "https://example.org/rel/widget" can be found by expanding the | |||
"https://example.org/vars/widget_id" variable into the template | "https://example.org/vars/widget_id" variable into the template | |||
given. | given. | |||
If the current context of the message that the header appears within | If the current context of the message that the header appears within | |||
is "https://example.org/", the same information could be conveyed by | is "https://example.org/", the same information could be conveyed by | |||
skipping to change at line 195 ¶ | skipping to change at page 5, line 10 ¶ | |||
3. Security Considerations | 3. Security Considerations | |||
The security consideration for the Link header field in [WEB-LINKING] | The security consideration for the Link header field in [WEB-LINKING] | |||
and those for URI Templates [URI-TEMPLATE] both apply. | and those for URI Templates [URI-TEMPLATE] both apply. | |||
4. IANA Considerations | 4. IANA Considerations | |||
This specification enters the "Link-Template" into the Hypertext | This specification enters the "Link-Template" into the Hypertext | |||
Transfer Protocol (HTTP) Field Name Registry. | Transfer Protocol (HTTP) Field Name Registry. | |||
Field Name: Link-Template | o Field Name: Link-Template | |||
Status: permanent | ||||
Specification document: [this document] | o Status: permanent | |||
o Specification document: [this document] | ||||
5. Normative References | 5. Normative References | |||
[HTTP] Fielding, R., Nottingham, M., and J. Reschke, "HTTP | [HTTP] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, | |||
Semantics", draft-ietf-httpbis-semantics-19 (work in | Ed., "HTTP Semantics", STD 97, RFC 9110, | |||
progress), September 2021. | DOI 10.17487/RFC9110, June 2022, | |||
<https://www.rfc-editor.org/info/rfc9110>. | ||||
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate | [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate | |||
Requirement Levels", BCP 14, RFC 2119, | Requirement Levels", BCP 14, RFC 2119, | |||
DOI 10.17487/RFC2119, March 1997, | DOI 10.17487/RFC2119, March 1997, | |||
<https://www.rfc-editor.org/info/rfc2119>. | <https://www.rfc-editor.org/info/rfc2119>. | |||
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC | [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC | |||
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, | 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, | |||
May 2017, <https://www.rfc-editor.org/info/rfc8174>. | May 2017, <https://www.rfc-editor.org/info/rfc8174>. | |||
[STRUCTURED-FIELDS] | [STRUCTURED-FIELDS] | |||
Nottingham, M. and P-H. Kamp, "Structured Field Values for | Nottingham, M. and P. Kamp, "Structured Field Values for | |||
HTTP", RFC 8941, DOI 10.17487/RFC8941, February 2021, | HTTP", RFC 8941, DOI 10.17487/RFC8941, February 2021, | |||
<https://www.rfc-editor.org/info/rfc8941>. | <https://www.rfc-editor.org/info/rfc8941>. | |||
[URI] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform | [URI] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform | |||
Resource Identifier (URI): Generic Syntax", STD 66, | Resource Identifier (URI): Generic Syntax", STD 66, | |||
RFC 3986, DOI 10.17487/RFC3986, January 2005, | RFC 3986, DOI 10.17487/RFC3986, January 2005, | |||
<https://www.rfc-editor.org/info/rfc3986>. | <https://www.rfc-editor.org/info/rfc3986>. | |||
[URI-TEMPLATE] | [URI-TEMPLATE] | |||
Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., | Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., | |||
End of changes. 17 change blocks. | ||||
47 lines changed or deleted | 48 lines changed or added | |||
This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/ |