Network Working Group | J. Reschke |
Internet-Draft | greenbytes |
Intended status: Standards Track | July 2009 |
Expires: January 2010 |
This Internet-Draft is submitted to IETF in full conformance with the provisions of BCP 78 and BCP 79.¶
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts.¶
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”.¶
The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt.¶
The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html.¶
This Internet-Draft will expire in January 2010.¶
Copyright (c) 2009 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 in effect on the date of publication of this document (http://trustee.ietf.org/license-info). Please review these documents carefully, as they describe your rights and restrictions with respect to this document.¶
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 header through which a server can advertise a substitute URL that an HTTP client subsequently can use with the GET method.¶
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 <http://lists.w3.org/Archives/Public/ietf-http-wg/>.¶
XML versions, latest edits and the issues list for this document are available from <http://greenbytes.de/tech/webdav/#draft-reschke-http-get-location>.¶
I edit (type: edit, status: open) | ||
julian.reschke@greenbytes.de | 2007-07-27 | Umbrella issue for editorial fixes/enhancements. |
Associated changes in this document: C.2, E. |
Several HTTP ([RFC2616]) 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 header through which a server can advertise a substitute URL that an HTTP client subsequently can use with the GET method.¶
The GET-Location entity header 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 header can only used on responses to safe methods.¶
Syntax (using the the augmented Backus-Naur Form (BNF) defined in Section 2.1 of [RFC2616]):
GET-Location = "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 [RFC2616], Section 3.3.2> entity-tag = <defined in [RFC2616], Section 3.11> path-absolute = <defined in [RFC3986], Section 3.3> quoted-string = <defined in [RFC2616], Section 2.2> query = <defined in [RFC3986], Section 3.4> token = <defined in [RFC2616], Section 2.2>
Where: ¶
The freshness lifetime for the information obtained from the GET-Location header 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 header, 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 specification introduces no new security considerations beyond those discussed in Section 15 of [RFC2616].¶
This document specifies the new HTTP header 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 header, 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: <http://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="http://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 header would be to re-use an existing header, such as the Link header defined in Section 19.6.2 of [RFC2068]. 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="↓http://purl.oclc.org/NET/webdav/mount/getlocationhttp://purl.net/NET/webdav/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 header for the GET operation.¶
Should we allow servers to return URI templates ([draft-gregorio-uritemplate]), 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 <http://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 header, Multistatus body extension.¶