XRD Discovery For HTTP and HTTPS URLs
Note: This is a draft specification.
Contents |
Abstract
XRD Discovery For HTTP and HTTPS URLs defines how to retrieve an XRD service discovery element for an HTTP or HTTPS URL.
Terminology
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].
Overview
The purpose of this specification is to describe how to map an HTTP or HTTPS URL onto an XRD service discovery element for the purposes of XRD-based service discovery as described in[XRDS_Service_Discovery].
URI Recognition
This specification is applicable only to URIs using the HTTP and HTTPS protocols. That is, URLs with a prefix of either http:// or https://.
Discovery of the XRD Element
Locating the XRDS Document
The first step is to obtain a full XRDS document. The process for locating and obtaining this document is given in the following sections.
Initiation
Discovery is intiated by the Relying Party Agent with an initial HTTP request to the provided HTTP or HTTPS URL.
The request MUST be either a GET or a HEAD request.
The GET or HEAD request MAY include an HTTP Accept request-header (HTTP 14.1) specifying the media type application/xrds+xml.
Response
The response MUST be one of:
- An HTML document with a <head> element that includes a <meta> element with http-equiv attribute, X-XRDS-Location,
- HTTP response-headers that include an X-XRDS-Location response-header, together with a document
- HTTP response-headers only, which MAY include an X-XRDS-Location response-header, a content-type response-header specifying media type application/xrds+xml, or both.
- A document of media type application/xrds+xml.
Resource Descriptor URL
The response MAY include an X-XRDS-Location HTTP response-header; the value of that header MUST be the URL of an XRDS document.
The response MAY include an HTML document with a <head> element containing a <meta> element whose http-equiv attribute is X-XRDS-Location; the value of that attribute MUST be the URL of an XRDS document.
If the response includes Yadis Resource Descriptor URLs in both an HTTP response-header and an HTML document <head> element, the XRDS document URL in the HTTP response-header MUST be used.
The XRDS document URL MUST be given as an absolute URL; it MUST locate an XRDS document.
If the response includes both a content-type response-header specifying media type application/xrds+xml and the URL of an XRDS document, then the XRDS document is located by that XRDS document URL.
Document
If the response does not include a Resource Descriptor URL and the response is a document of media type application/xrds+xml, then that document MUST be an XRDS document.
Second Request
If the response includes an XRDS document URL, the Relying Party Agent MUST request the document located by that URL.
If the response to an HTTP HEAD request does not contain am XRDS document URL, the Relying Party Agent MUST then issue an HTTP GET request to the original HTTP URL.
Third Request
The response to an HTTP GET request that follows an HTTP HEAD request MUST be handled as prescribed in 6.2.6 for an initial HTTP GET request. This MAY result in a third request using an XRDS document URL.
Termination
When the Relying Party Agent obtains an XRDS document, the document is processed as described in[xrds_document_processing].
Failure
If none of the requests succeed in obtaining an XRDS document then the URL used in the initial request does not support XRDS-based service discovery or there has been a failure.
XRDS Document Processing
The XRDS document will contain one or more XRD elements as described in[XRDS_Service_Discovery]. This protocol terminates by returning the final or only XRD element in the document.
If there are no XRD elements present in the document, or the document does not conform to the XRDS Service Discovery schema as defined in[XRDS_Service_Discovery], XRDS discovery fails.
