[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Preview of new LRDD draft
Network Working Group E. Hammer-Lahav Internet-Draft Yahoo! Intended status: Informational October 27, 2009 Expires: April 30, 2010 Link-based Resource Descriptor Discovery (LRDD) draft-hammer-discovery-04 Status of this Memo 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 on April 30, 2010. Copyright Notice 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. Abstract This memo describes a process for obtaining information about a resource identified by a URI using Web linking. The 'information about a resource', a resource descriptor, provides machine-readable information that aims to increase interoperability and enhance interactions with the resource. This memo describe methods for locating and obtaining descriptors, but leaves the descriptor format and its interpretation out of scope. Table of Contents 1. Introduction 2. Notational Conventions 3. Process Template 4. Identifying Descriptor Location 4.1. The 'LINK' Element 4.2. The HTTP Link Header 4.3. The Host Metadata Document 4.4. Method Selection Profiles 5. Obtaining Resource Descriptor 6. Security Considerations 7. IANA Considerations Appendix A. Acknowledgments Appendix B. Document History 8. References 8.1. Normative References 8.2. Informative References Author's Address 1. Introduction [[ This revision is a rough edit submitted early to share the document progress and new direction, using a process template approach. Feedback should ignore editorial changes. ]] This memo describes a simple process for locating descriptors for URI-identified resources using the Web Linking framework described by [I-D.nottingham-http-link-header]. Resource descriptors are machine- readable documents (usually based on well known serialization languages such as XML, RDF, and JSON), which provide information about resources (resource metadata) for the purpose of promoting interoperability and assist with interacting with unknown resources that support known interfaces. Given the wide range of metadata needs, no single descriptor format or retrieval method can adequately accommodate every use case. While there are many methods for obtaining resource descriptors (e.g., HTTP headers, WebDAV's PROPFIND [RFC4918], HTTP OPTIONS, URIQA's MGET [URIQA]), and multiple ways in which Web Linking can be used to associate a resource to its descriptor, LRDD provides a reusable process template to accomodate the common discovery needs of many Web protocols. For example, a web page about an upcoming meeting can provide in its descriptor document the location of the meeting organizer's free/busy information to potentially negotiate a different time. A social network profile page descriptor can identify the location of the user's address book as well as accounts on other sites. A web service implementing an API with optional components can advertise which of these are supported. This memo describes the first step in the discovery process in which the resource descriptor document is located and retrieved. Other steps, which are outside the scope of this memo, include parsing the descriptor document based on its format (such as [W3C.PR-powder-dr-20090604] and [OASIS.XRD-1.0]) and utilizing it based on the application. Please discuss this draft on the apps-discuss@ietf.org [1] mailing list. 2. Notational Conventions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119]. 3. Process Template This memo define a process template for associating and obtaining resource descriptors. While the process is identical in any LRDD implementation, some of the parameters are protocol-specific and MUST be defined when LRDD is referenced: o Relation Type - LRDD uses typed link relations as defined by [I-D.nottingham-http-link-header] to associate a resource with its descriptor document. Protocols SHOULD choose a relation type carefully to ensure it does not conflict with existing or future deployments using the same relation type. The relation type MAY be a registered short name or an extension URI. o Method Selection Profile - LRDD defines three profiles for selecting links across the three linking methods: resource- priority, host-priority, and equal-priority as described in Section 4.4. For example, a protocol utilizing LRDD can reference it by instructing its clients to "use LRDD to obtain a resource description using relation type 'http://example.com/rel/description' and the 'resource-priority' selection profile". 4. Identifying Descriptor Location The descriptor location (URI) is a function of the resource URI. Each of the following three methods is performed by using the resource URI to identify its descriptor URI. The methods described in this memo express the location of the resource descriptor as a link relation, utilizing the link framework defined by [I-D.nottingham-http-link-header]. The association of a descriptor document with the resource it describes is declared using the selected link relation type as described in Section 3. In many cases, a request for one URI leads to requesting other URIs, as is the case with HTTP redirections. Because the decision whether to use such URIs is application-specific, LRDD is constrained to a single URI identifying the resource. Any other resource URIs received while performing discovery MUST be considered as a separate and discrete input into the discovery function. If a resource URI obtained during the performance of these methods is found to be more relevant to the application, the discovery process MUST be restarted with the new resource URI as its input. For example, an HTTP HEAD request for URI A returns a redirection (307) response with a set of links, and identifies the temporary location of the representation at URI B. An HTTP HEAD request for URI B returns a successful (200) response with its own set of links. An application MAY choose to define a process in which the two sets of links are obtained, prioritized, and utilized, however, it MUST do so by explicitly instructing the client to perform LRDD multiple times, as each is considered separate and distinct process. Each method presents a different set of requirements. The criteria used to determine which methods a server SHOULD support and client SHOULD attempt are based on a combination of factors (the order in which applicable methods are attempted is described in Section 4.4): o The ability to offer and obtain a representation of the resource by dereferencing its URI. o The availability of a representation supporting 'LINK' markup compatible with [I-D.nottingham-http-link-header]. o The availability of an HTTP representation of the resource and the ability to provide and access link information in its response header. 4.1. The 'LINK' Element The 'LINK' element method is limited to resources with an available markup representation that supports typed-relations using the 'LINK' element, such as HTML [W3C.REC-html401-19991224], XHTML [W3C.REC-xhtml1-20020801], and Atom [RFC4287]. Other markup formats are permitted as long as the semantics of their 'LINK' elements are fully compatible with the link framework defined in [I-D.nottingham-http-link-header]. This method requires the retrieval of a resource representation. While HTTP is the most common transport for such documents, this method is transport independent. For example: <LINK href="http://example.com/resource;about" rel="http://example.com/rel/description" type="application/xrd+xml"> A client trying to obtain the location of the resource's descriptor using this method SHALL: 1. Retrieve a representation of the resource using the applicable transport for that resource URI. If the markup document is obtained using HTTP, it MUST only be used by the client if the document is a valid representation of the resource identified by the HTTP request URI, typically in a response with a successful (2xx) or redirection (3xx) status code. If no such valid representation of the request URI is found, the method fails. 2. Parse the document as defined by its format specification and look for 'LINK' elements with a "rel" attribute value containing the chosen relation type. The client MUST obey the document markup schema and ignore any invalid elements (such as 'LINK' elements outside the 'HEAD' section of an HTML document). This is done to avoid unintentional markup from other parts of the document to be used for discovery purposes, which can have vast impact on usability and security. 3. The descriptor location is obtained from the value of the "href" attribute in the selected 'LINK' element. If more than one matching link is found, process them in document order until a descriptor document is successfully obtained as described in Section 5. Some 'LINK' elements can allow multiple relation types in a single "rel" attribute (for example 'rel="http://example.com/rel/description copyright"'). Clients MUST properly process such multiple relation "rel" attributes as defined by the format specification. 4.2. The HTTP Link Header The HTTP Link header method is limited to resources for which an HTTP GET or HEAD request returns a 2xx, 3xx, or 4xx HTTP response [RFC2616]. This method uses the Link header defined in [I-D.nottingham-http-link-header] and requires the retrieval of a resource representation header. For example: Link: <http://example.com/resource;about>; rel="http://example.com/rel/description"; type="application/xrd+xml" A client trying to obtain the location of the resource's descriptor using this method SHALL: 1. Make an HTTP (or HTTPS as required) GET or HEAD request to the resource URI to obtain a valid response header. If the HTTP response carries a status code other than successful (2xx), redirection (3xx), or client error (4xx), the method fails. 2. Parse the HTTP response header and look for Link headers with a "rel" parameter value containing the chosen relation type. 3. The descriptor location is obtained from the "<>" enclosed URI- reference in the selected Link header. If more than one matching link is found, process them in any order until a descriptor document is successfully obtained as described in Section 5. Link headers can include multiple relation types in a single "rel" parameter (for example 'rel="http://example.com/rel/description copyright"'). Clients MUST properly process such multiple relation "rel" attributes as defined by [I-D.nottingham-http-link-header]. 4.3. The Host Metadata Document The host metadata document method is available for any resource identified by a URI whose authority supports the host-meta document defined in [I-D.hammer-hostmeta]. This method does not require obtaining any representation of the resource, and operates solely using the resource URI. The link relation between the resource URI and the descriptor URI is obtained by using a template contained in the host-meta document. By applying the host-wide template to an individual resource URI, a resource-specific link is produced which can be used to indicate the location of the descriptor document for that resource, bypassing the need to access or provide a representation for it. For example (line breaks are for formatting only, and are not allowed in the document): <Link> <Rel>http://example.com/rel/description</Rel> <URITemplate>{+uri};about</URITemplate> <MediaType>application/xrd+xml"</MediaType> </Link> A client trying to obtain the location of the resource's descriptor using this method SHALL: 1. Retrieve the host-meta document for URI's authority as defined by [I-D.hammer-hostmeta] section 4. If the request fails to retrieve a valid host-meta document, the method fails. 2. Parse host-meta document and look for 'Link' elements with a "rel" attribute value containing the chosen relation type and a 'URITemplate' child element. 3. The descriptor location is constructed by applying the template obtained from the selected Link element to the resource URI as described by [I-D.hammer-hostmeta] section 3.2.1. If more than one matching link is found, process them in document order until a descriptor document is successfully obtained as described in Section 5. 4.4. Method Selection Profiles LRDD defines three method selection profiles for deciding the order in which each of the three methods (when applicable) MUST be attempted until a descriptor document is obtained successfully: o Resource-Priority - Priority is given to the individual resource over the linking policies of the host. The order in which the methods SHALL be attempted is: 'LINK' element, 'Link' header, and host-meta. o Host-Priority - Priority is given to the linking policies of the host over those defined by individual resources. The order in which the methods SHALL be attempted is: host-meta, 'Link' header, and 'LINK' element. o Equal-Priority - The protocol-specific links from each method must produce the same resource descriptor document and MAY be attempted in any order, as long as the method is applicable to the resource type and URI. 5. Obtaining Resource Descriptor Once the desired descriptor URI has been obtained, the descriptor document is retrieved. If the descriptor URI scheme is "http" or "https", the document is obtained via an HTTP GET request to the identified URI. The client MUST obey HTTP redirections (3xx), and the descriptor document is considered valid only if retrieved with a successful HTTP response status (2xx). If the descriptor format or media type do not match those supported by the protocol, the client SHOULD ignore the descriptor document and treat it as if it was linked using a different relation type than the selected protocol relation type as described in Section 3. 6. Security Considerations The methods used to perform discovery are not secure, private or integrity-guaranteed, and due caution should be exercised when using them. Applications that perform LRDD SHOULD consider the attack vectors opened by automatically following, trusting, or otherwise using links gathered from 'LINK' elements, HTTP Link headers, or host-meta documents. 7. IANA Considerations No IANA actions are required by this document. Appendix A. Acknowledgments Inspiration for this memo derived from previous work on a descriptor format called XRDS-Simple, which in turn derived from another descriptor format, XRDS. Previous discovery workflows include Yadis which is currently used by the OpenID community. While suffering from significant shortcomings, Yadis was a breakthrough approach to performing discovery using extremely restricted hosting environments, and this memo has strived to preserve as much of that spirit as possible. The author wishes to thanks the OASIS XRI TC and WebFinger communities for their support, encouragement, and enthusiasm for this work. Special thanks go to Phil Archer, Lisa Dusseault, Joseph Holsten, Mark Nottingham, John Panzer, Drummond Reed, and Jonathan Rees for their invaluable feedback. Appendix B. Document History [[ to be removed by the RFC editor before publication as an RFC ]] -04 o Focused memo on Web-linking-based discovery only instead of positioning it as better or more appropriate than other methods. Removed analysis appendix and discussion of discovery types and removed many informative references. Rewrote as a process template with protocol-specific parameters. o Moved the Link-Pattern field and template syntax to new host-meta draft. -03 o Added protocol name LRDD (pronounced 'lard'). o Fixed Link-Pattern examples to include missing semicolons. -02 o Changed focus from an HTTP-based process to Link-based process. o Completely revised and restructured document for better clarity. o Realigned the methods to produce consistent results and changed the way redirections and client-errors are handled. o Updated to use newer version of site-meta, now called host-meta, including a new plaintext-based format to replace the previous XML format. o Renamed Link-Template to Link-Pattern to avoid future conflict with a previously proposed Link-Template HTTP header. o Removed support for the "scheme" Link-Template parameter. o Replaced restrictions with interoperability recommendations. o Added IANA considerations per new host-meta registry requirements. -01 o Rename 'resource discovery' to 'descriptor discovery'. o Added informative reference to Metalink. o Clarified that the resource descriptor URI can use any URI scheme, not just "http" or "https". o Removed comment regarding redirects when using 'LINK' Elements. o Clarified that HTTPS must be used with "https" URIs for both Link headers and host-meta retrieval. o Removed DNS verification step for host-meta with schemes other then "http" and "https". Replaced with a general discussion of authority and a security consideration comment. o Organized host-meta section into another sub-section level. o Enlarged the template vocabulary from a single "uri" variable to include smaller URI components. o Added informative reference to RFC 2295 in analysis appendix. -00 o Initial draft. 8. References 8.1. Normative References [I-D.hammer-hostmeta] Hammer-Lahav, E., "Host-Meta: Web Host Metadata", draft-hammer-hostmeta-01 (work in progress), October 2009. [I-D.nottingham-http-link-header] Nottingham, M., "Web Linking", draft-nottingham-http-link-header-06 (work in progress), July 2009. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. [RFC4287] Nottingham, M., Ed. and R. Sayre, Ed., "The Atom Syndication Format", RFC 4287, December 2005. [W3C.REC-html401-19991224] Hors, A., Raggett, D., and I. Jacobs, "HTML 4.01 Specification", World Wide Web Consortium Recommendation REC-html401-19991224, December 1999, <http://www.w3.org/TR/1999/REC-html401-19991224>. [W3C.REC-xhtml1-20020801] Pemberton, S., "XHTML[TM] 1.0 The Extensible HyperText Markup Language (Second Edition)", World Wide Web Consortium Recommendation REC-xhtml1-20020801, August 2002, <http://www.w3.org/TR/2002/REC-xhtml1-20020801>. 8.2. Informative References [OASIS.XRD-1.0] Hammer-Lahav, E. and W. Norris, "Extensible Resource Descriptor (XRD) Version 1.0 (work in progress)", <http:// www.oasis-open.org/committees/download.php/34815/ xrd-1.0-cd01.html>. [RFC4918] Dusseault, L., "HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV)", RFC 4918, June 2007. [URIQA] Nokia, "The URI Query Agent Model", <http://sw.nokia.com/uriqa/URIQA.html>. [W3C.PR-powder-dr-20090604] Smith, K., Perego, A., and P. Archer, "Protocol for Web Description Resources (POWDER): Description Resources", World Wide Web Consortium PR PR-powder-dr-20090604, June 2009, <http://www.w3.org/TR/2009/PR-powder-dr-20090604>. URIs [1] <https://www.ietf.org/mailman/listinfo/apps-discuss> Author's Address Eran Hammer-Lahav Yahoo! Email: eran@hueniverse.com URI: http://hueniverse.com
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]