| Network Working Group | J. Reschke |
| Internet-Draft | greenbytes |
| Intended status: Standards Track | July 7, 2024 |
| Expires: January 8, 2025 |
Several hypertext transfer protocol (HTTP) extensions use methods other than GET to expose information. This has the drawback that this kind of information is harder to identify (missing a URL to which a GET request could be applied) and to cache.¶
This document specifies a simple extension field through which a server can advertise a substitute URL that an HTTP client subsequently can use with the GET method.¶
This note is to be removed before publishing as an RFC.¶
Distribution of this document is unlimited. Please send comments to the Hypertext Transfer Protocol (HTTP) mailing list at ietf-http-wg@w3.org, which may be joined by sending a message with subject "subscribe" to ietf-http-wg-request@w3.org.¶
Discussions of the HTTP working group are archived at https://lists.w3.org/Archives/Public/ietf-http-wg/.¶
XML versions, latest edits and the issues list for this document are available from https://greenbytes.de/tech/webdav/#draft-reschke-http-get-location.¶
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 January 8, 2025.¶
Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved.¶
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶
| I edit (type: edit, status: open) | ||
| julian.reschke@greenbytes.de | 2007-07-27 | Umbrella issue for editorial fixes/enhancements. |
Several HTTP ([RFC7230]) extensions use methods other than GET to expose information. This has the drawback that this kind of information is harder to identify (missing a URL to which a GET request could be applied) and to cache.¶
This document specifies a simple extension field through which a server can advertise a substitute URL that an HTTP client subsequently can use with the GET method.¶
The GET-Location entity field identifies a substitute resource that can be used in subsequent requests for the same information, but using the GET method.¶
Note that, by definition, the GET-Location field can only used on responses to safe methods.¶
The field value syntax (using the augmented Backus-Naur Form (BNF) defined in Section 7 of [RFC7230]) is:¶
GET-Location = "<" Simple-ref ">"
*( ";" location-directive ) )
location-directive = "etag=" entity-tag
| "max-age" "=" delta-seconds
| location-extension
location-extension = token [ "=" ( token | quoted-string ) ]
Simple-ref = absolute-URI | ( path-absolute [ "?" query ] )
absolute-URI = <defined in [RFC3986], Section 4.3>
delta-seconds = <defined in [RFC7234], Section 1.1>
entity-tag = <defined in [RFC7232], Section 2.3>
path-absolute = <defined in [RFC3986], Section 3.3>
quoted-string = <defined in [RFC7230], Section 3.2.6>
query = <defined in [RFC3986], Section 3.4>
token = <defined in [RFC7230], Section 3.2.6>
Where:¶
The freshness lifetime for the information obtained from the GET-Location field does not depend on the cacheability of the response it was obtained from (which, in general, may not be cacheable at all). The "max-age" directive allows the server to specify after how many seconds a client should discard knowledge about the alternate resource. In absence of that field, clients SHOULD discard the information after 3600 seconds.¶
There is no direct relation between the status code of the HTTP response that included GET-Location and the status codes for subsequent GET requests on the substitute resource. For instance, GET-Location could be included in a 207 response to PROPFIND ([RFC4918], Section 9.1), but the response code for a succesful GET on the substitute resource would usually be 200.¶
Note that servers may, but are not required to support methods other than GET or head on the substitute resource.¶
This document specifies the new HTTP field listed below, to be added to the permanent registry (see [RFC3864]).¶
This document has benefited from thoughtful discussion by Stefan Eissing and Henrik Nordstrom.¶
In this example the client uses the WebDAV PROPFIND method ("HTTP Extensions for Web Distributed Authoring and Versioning", [RFC4918], Section 9.1) to get a list of all collection members, along with their DAV:resourcetype property ([RFC4918], Section 15.9):¶
>>Request¶
PROPFIND /collection/ HTTP/1.1
Host: example.com
Depth: 1
Content-Type: application/xml
<propfind xmlns="DAV:">
<prop>
<resourcetype/>
</prop>
</propfind>
The response contains the requested information, plus the GET-Location field, identifying a separate resource which can provide the same information using the HTTP GET method:¶
>>Response¶
HTTP/1.1 207 Multi-Status
Content-Type: application/xml
GET-Location: <https://example.com/collection/;members>; etag="123";
max-age=3600
<multistatus xmlns="DAV":>
<response>
<href>/collection/</href>
<propstat>
<prop>
<resourcetype><collection/></resourcetype>
</prop>
<status>HTTP/1.1 200 OK</status>
</propstat>
</response>
<response>
<href>/collection/member</href>
<propstat>
<prop>
<resourcetype/>
</prop>
<status>HTTP/1.1 200 OK</status>
</propstat>
</response>
</multistatus>
The response provided the URL of the substitute resource, so when the client wishes to refresh the collection information, it uses that URI. The response contained the entity tag for the data being returned, so it can make the request conditional:¶
>>Request¶
GET /collection/;members HTTP/1.1 Host: example.com Accept: application/xml If-None-Match: "123"
The information did not change, so the server does not need to return new data:¶
>>Response¶
HTTP/1.1 304 Not Modified
Later on, the client tries again. This time, however, a second member has been added:¶
>>Request¶
GET /collection/;members HTTP/1.1 Host: example.com Accept: application/xml If-None-Match: "123"
>>Response¶
HTTP/1.1 200 OK
Content-Type: application/xml
ETag: "124"
<multistatus xmlns="DAV":>
<response>
<href>/collection/</href>
<propstat>
<prop>
<resourcetype><collection/></resourcetype>
</prop>
<status>HTTP/1.1 200 OK</status>
</propstat>
</response>
<response>
<href>/collection/member</href>
<propstat>
<prop>
<resourcetype/>
</prop>
<status>HTTP/1.1 200 OK</status>
</propstat>
</response>
<response>
<href>/collection/member2</href>
<propstat>
<prop>
<resourcetype/>
</prop>
<status>HTTP/1.1 200 OK</status>
</propstat>
</response>
</multistatus>
Finally, the collection has been removed by somebody else. The client tries a refresh:¶
>>Request¶
GET /collection/;members HTTP/1.1 Host: example.com Accept: application/xml If-None-Match: "124"
>>Response¶
HTTP/1.1 404 Not Found
Note that it may be hard to compute entity tags for more complex PROPFIND responses. For instance, most properties depend on the state of the collection member, not the state of the collection itself, and thus the response will change even though the state of the collection itself did not change.¶
This is why this extension leaves it to the server whether to return a GET-Location at all, and if so, whether to return cache validators along with it.¶
Here, the client uses the WebDAV PROPFIND method ([RFC4918], Section 9.1) to obtain a custom property:¶
>>Request¶
PROPFIND /collection/member HTTP/1.1
Host: example.com
Depth: 0
Content-Type: application/xml
<propfind xmlns="DAV:">
<prop>
<title xmlns="https://ns.example.com/"/>
</prop>
</propfind>
>>Response¶
HTTP/1.1 207 Multi-Status
Content-Type: application/xml
GET-Location: </collection/member;prop=title>; etag="1"
<multistatus xmlns="DAV":>
<response>
<href>/collection/member</href>
<propstat>
<prop>
<title xmlns="http://ns.example.com/"
>Document Title</title>
</prop>
<status>HTTP/1.1 200 OK</status>
</propstat>
</response>
</multistatus>
>>Request¶
GET /collection/member;prop=title HTTP/1.1 Host: example.com If-None-Match: "1"
>>Response¶
HTTP/1.1 304 Not Modified
Later, the request is repeated after the title property indeed changed...:¶
>>Request¶
GET /collection/member;prop=title HTTP/1.1 Host: example.com If-None-Match: "1"
>>Response¶
HTTP/1.1 200 OK
Content-Type: application/xml
ETag: "2"
<multistatus xmlns="DAV":>
<response>
<href>/collection/member</href>
<propstat>
<prop>
<title xmlns="http://ns.example.com/"
>New Document Title</title>
</prop>
<status>HTTP/1.1 200 OK</status>
</propstat>
</response>
</multistatus>
Although this example may look like every WebDAV property would need a separate entity tag, this is of course not the case. For instance, a server that stores all custom properties in a single place (like a properties file) could use the same computation for the entity tag for all properties. Also, it could implement resources representing multiple custom property values the same way.¶
Here, the client uses the DeltaV DAV:version-tree report ("Versioning Extensions to WebDAV", [RFC3253], Section 3.7) to obtain the members of the version history of a version-controlled resource.¶
>>Request¶
REPORT /collection/member HTTP/1.1
Host: example.com
Depth: 0
Content-Type: application/xml
<version-tree xmlns="DAV:">
<prop>
<resourcetype/>
</prop>
</version-tree>
>>Response¶
HTTP/1.1 207 Multi-Status
Content-Type: application/xml
GET-Location: </version-storage/12345/;justmembers>
<multistatus xmlns="DAV":>
<response>
<href>/version-storage/12345/V1</href>
<propstat>
<prop>
<resourcetype><collection/></resourcetype>
</prop>
<status>HTTP/1.1 200 OK</status>
</propstat>
</response>
<response>
<href>/version-storage/12345/V2</href>
<propstat>
<prop>
<resourcetype><collection/></resourcetype>
</prop>
<status>HTTP/1.1 200 OK</status>
</propstat>
</response>
</multistatus>
Note that in this case, the substitute resource can be almost identical to the one from the PROPFIND/Depth:1 example: the only difference being that the report result does not contain a DAV:response element for the collection itself.¶
An alternative to introducing a new field would be to re-use an existing field, such as the Link field defined in [RFC8288]. Note that this still would require registering a link relation.¶
The example from Appendix A.1 would then read like this:¶
Link: </collection/;members>;
rel=getlocation; etag="123"; max-age=3600
Observing that the whole proposal tries to deal with WebDAV related shortcomings, it may make sense to constrain the solution to WebDAV response bodies, thereby not having to introduce anything that would be visible outside WebDAV.¶
A very simple approach would be to embed the information in the DAV:multistatus ([RFC4918], Section 14.16) response body.¶
Re-using the example in Appendix A.1, this could look like this:¶
HTTP/1.1 207 Multi-Status
Content-Type: application/xml
<multistatus xmlns="DAV":>
<gl:get-location
xmlns:gl="https://purl.oclc.org/NET/webdav/mount/getlocation">
<href>/collection/;members</href>
<getetag>"123"</getetag>
<gl:max-age>3600</gl:max-age>
<gl:get-location
<response>
<href>/collection/</href>
<propstat>
<prop>
<resourcetype><collection/></resourcetype>
</prop>
<status>HTTP/1.1 200 OK</status>
</propstat>
</response>
<response>
<href>/collection/member</href>
<propstat>
<prop>
<resourcetype/>
</prop>
<status>HTTP/1.1 200 OK</status>
</propstat>
</response>
</multistatus>
Should it be possible to use Content Negotiation on the resource identified by GET-Location? A use case could be a metadata provider that would support different formats, such as WebDAV's multistatus format (MIME type missing!), RDF, JSON, whatever.¶
This could be done using a location-extension specifying the Accept field for the GET operation.¶
Should we allow servers to return URI templates ([RFC6570]), so that clients can compute substitute URLs for other requests as well?¶
For instance, this could be done by allowing a URI template instead of the Simple-ref, and to return another template specifying how to derive the template variable from the Request-URI:¶
>>Request¶
PROPFIND /documents/a/b HTTP/1.1 Host: example.com Depth: 0 Content-Type: application/xml
>>Response¶
HTTP/1.1 207 Multi-Status
Content-Type: application/xml
GET-Location: </metadata/{path};members>; path-template=</a/b/{path}>
...
So in this case, the actual URI to be used would be <https://example.com/metadata/a/b;members>.¶
Do we need a registry for new location-directive values?¶
Add and resolve issues "non-get" and "status-codes". Add issue "content-location". Add "Acknowledgments" Section. Update uri-template reference. Discuss more alternative approaches: Link field, Multistatus body extension.¶
Update terminology and references.¶