.. -*- rst -*- YADIS Protocol ============== :Date: 13 January 2006 .. contents:: .. sectnum:: Protocol Overview ----------------- The YADIS [#]_ protocol enables discovery of service definitions from an ``http://`` or ``https://`` URL. The protocol consists of performing HTTP requests to obtain a YADIS Resource Descriptor. Terminology ----------- YADIS URL an ``http://`` or ``https://`` URL that supports the YADIS protocol YADIS Resource Descriptor the document that results from performing the YADIS protocol Relying Party the entity using the YADIS protocol to discover what services are available for a YADIS URL Agent the software acting on behalf of the relying party Specification ------------- The protocol starts with an HTTP [#]_ request for the YADIS URL. The response must contain either a URL for the YADIS resource descriptor or the resource descriptor itself. If it does not, then the URL is not a YADIS URL. The YADIS protocol uses HTTP or HTTPS requests as necessary for the URL it is working with. Whenever the agent is instructed to make an HTTP request, HTTPS is implied for ``https://`` URLs. When using HTTP to retrieve a document, redirects that are encountered should be followed, up to a reasonable maximum. A simple guideline is a maximum of 10 redirects, similar to most web browsers. The final HTTP response is only successful if it has a 200 response code. Requesting the Document ....................... The agent performs an HTTP ``GET`` request for the YADIS URL. The agent may use server-driven content negotiation [#]_ to encourage the server to respond immediately with a YADIS resource descriptor. If the agent is using content negotiation, it should request the ``application/xrds+xml`` MIME [#]_ type. Using content negotiation reduces the number of HTTP requests if used with a server that supports it. The agent may perform an HTTP ``HEAD`` request if it expects the server response to include an ``X-YADIS-Location`` HTTP header. If the header is not present, the protocol must be restarted with an HTTP ``GET`` request. Handling the Response ..................... If the HTTP response contains an ``X-YADIS-Location`` header, the header value is the location of the `YADIS resource descriptor`_. The header name is not case sensitive. If the header is not present and the MIME type of the response indicates an HTML document [*]_, the agent must parse the document. The document must contain a ```` tag [#]_ with an ``http-equiv`` attribute whose value, ignoring case, is ``X-YADIS-Location``. The tag must have a ``content`` attribute whose value is the location of the YADIS resource descriptor. The agent must only accept ```` tags that occur inside of the ``
`` element of the HTML document. If a location was found in either of the two previous cases, the location must be an absolute HTTP URL. The agent performs a HTTP ``GET`` request for that URL. If the request succeeds, the content returned must be a YADIS resource descriptor, regardless of the declared MIME type of the response. After retrieving the resource descriptor, the YADIS protocol is complete. If no ``X-YADIS-Location`` header is included in the server's response to the request for the YADIS URL and the MIME type of the response doesn't indicate HTML, the MIME type must be ``application/xrds+xml``. If it is, the server's response is the YADIS resource descriptor. Otherwise, the initial URL is not a YADIS URL. .. [*] Any version of HTML, including XHTML, is acceptable. YADIS Resource Descriptor ------------------------- The YADIS resource descriptor is a document that contains service descriptions associated with the YADIS URL. It uses the Extensible Resource Descriptor (XRD) format developed by the XRI Technical Committee [#]_ of the OASIS group [#]_ as part of XRI [#]_ resolution. This section includes a short description of the XRD format to supplement the official specification, which is in the XRI Resolution 2.0 specification [#]_. An XML schema for XRD documents can be found in Appendix A of that specification. The top-level element of an XRD document is the ``