XRI Busy Web Developer's Guide
From I-names Development Wiki
Contents |
BusyWebDevelopersGuide
Introduction
Describe with lots of examples how a web developer can use XRIs without having to understand the XRI resolution specification in any detail. Describe XRI (proxy) resolution as a set of fancy http URIs that respond to HTTP GET requests with special document types or an HTTP redirect.
XRI (proxy) resolution is the process of performing an HTTP GET on a special type of HTTP URI (a "fancy" HTTP URI) that identifies both a XRI resolution proxy and an XRI to be resolved at that proxy XRI. This GET results in an HTTP response that results in an HTTP redirect to another HTTP URI or one of several document types that describe the resource identified by the XRI embedded in the "fancy" HTTP URI.
There's a special section for Busy OpenID Developers (developers of openid libraries), who are a very small subset of web developers.
Those document types are one of:
- XRDS
- (extensible resource descriptor list) - contains a list of XRD elements, each corresponding to a delegation path in the XRI. Note: Busy web developers will almost never ask for this type of document. (4G)
- XRD
- (extensible resource descriptor) - contains a document describing the resource identified. Note: Really busy web developers would only ask for this document type when they want metadata from XRI resolution beyond service location URIs (described below).
- uri-list
- (list of URIs) - a uri-list of URIs which are service endpoints associated with the identified resource, as selected by the proxy resolver in accordance to the XRI resolution specification. This selection is typically performed by the proxy in conjunction the various service selection options described below. Note: this is the easiest result for busy web developers to use as long as the developer is just looking for service location URIs from XRI resolution
The Basic Request
Describe the basic YADIS-style request here. Talk about using the use of the accept-header to get the content type back
The basic proxy request is a simple HTTP request with the Accept header set to include one of several values:
- application/xrds+xml (returns an XRDS document)
- application/xrd+xml (returns an XRD document)
- text/uri-list (returns a uri list).
- any other media type causes the proxy to return an HTTP redirect to a resource with an acceptable media type (e.g. a HTML document, image, etc). This behavior can be modified by the _xrd_r query parameter (see Advanced Topics below)
Note that this HTTP request (with the above media types) could be applied to ANY HTTP URI, not just ones that are "fancy" (related to XRI). YADIS was defined to use this media-type negotiation mechanism ask for a XRD document from any HTTP URI. Thus, service description (or other metadata) can be discovered from a resource identified by any HTTP URI (fancy or not).
HXRI: The Fancy HTTP URI
So, when one is asking for resolution from a proxy resolver, what is the form of the HTTP URI (called a "HXRI")?
Here's an example: http://xri.net/=GabeW You'll notice that the first dns segment is "xri" and the path is an XRI.
We make the assumption that these fancy HTTP URIs comply with all the features described in this document.
An HXRI in a Web Browser
Discuss the redirect behavior of the proxy when being queried by a web browser
Introduction to the XRD
The Extensible Resource Descriptor ("XRD") is an XML element (and sometimes document) which contains:
- (optional) XRI-specific resolution data (safely ignored by busy web developers)
- zero or more service description elements ("service blocks").
- any other XML describing the XRI.
Give examples here
Service block
Services are any network addressible endpoint located by a URI and are described in service descirption elements ("Service" XML element). Along with the location URI (in the <URI> element), a service block typically has a type (in a <Type> element). For example, an openid authentication service endpoint has a type of http://openid.net/signon/2.0 and the uri is the URI where the openid authentication service can be accessed.
There are also fields for filtering out service blocks by "media type" and other metadata.
Note that a service block without a type is describing a plain HTTP URL accessed via plain ole HTTP - this is the function of mapping an XRI to a HTTP URL.
The location URI is actually a "base" URI - there are sometimes instructions in the XRD to add stuff to the base URI to construct the actual URI to be used for this XRI. Busy web developers, however, can ask the proxy to perform the URI construction on their behalf (via the uric=true media-type parameter), so the mechanics are not important.
Getting only URI List
Describe the use of the application/uri-list media type
In many cases, a busy web developer may not want to see an XRD at all. Instead the developer may want to simply ask for a list of service location URIs. This is done by asking for the media type text/uri-list in the Accept header. A request to http://xri.net/=GabeW using the header Accept: text/uri-list will result in a list of URIs that the proxy selects (and constructs) according to an intuitive filtering algorithm based on filtering criteria (e.g. filtering by service type or other service selection critera as described below) passed in as query parameters appended to the HXRI ("fancy URI"). (5D)
Offloading Work: Filtering and URI Construction
Describe what a server behind the fancy URI can do for you so you don't have to write code
In asking for a uri-list or XRD, you can ask the proxy do a number of things on your behalf as a client. These tasks are designed to make use of XRI resolution as simple as possible.
These options are passed in with an HXRI in two ways: either as media-type parameters, or as query parameters added to the end of the HXRI itself.
Service Selection: Filtering by Service Type
Describe the use of the _xrd_t parameter
Service Selection: Filtering by Media Type
Describe the user of the _xrd_m parameter
Service Selection: Filtering for "trusted" Canonical IDs
Service URI Construction: Proxy construction of Service location URIs
Service Selection: Turning it on and off
Describe when sep=true is useful, and what it does
Putting it all Together: The options you'll usually use
Advanced features
Trusted Resolution
Describe the use of the saml=true media type parameter
Controlling Whether a Proxy Follows References For You
Describe the use of the refs=true media type parameter
Asking for a Different Resolution Descriptor Type Using Query Parameter
Describe the user of the _xrd_r query parameter
Sometimes, you want to use an HXRI in a web page and you want to return a XRD or an XRDS as a result.
Asking for a Different Service Type Using Query Parameter
Describe the user of the _xrd_t query parameter
Sometimes, you want to use an HXRI in a web page and you want to get a redirect for a specific service type URI.
Asking for a Different Media Type When Getting a HTTP Redirect
Describe the user of the _xrd_m query parameter
When you want to use an HXRI in a web page and you want to get an HTTP redirect to an HTTP URI that can return a specific media type, you can add _xrd_m query parameter.
Busy OpenID Developers Guide
Describe what options to use if you are a busy OpenID Developer
