UserPreferences

PaceIntrospection


Abstract

Older versions of the AtomAPI had a file called the Introspection file. This file listed all of the different facets that a site supported. Real world experience has shown that this is a needed part of the API and this Pace reintroduces the concept with some minor changes.

Status

Open

Related and Conflicting Proposals

Key Questions

Proposal

Add the following to Section 5, the Functional Specification:

3.X Service Description

When editing the content of the website http://example.org/reilly, the first thing to do is find out the servers capabilites. Each server may only implement a subset of this specification, and the 'service' document lists the reources that each site makes available. The IntrospectionURI returns an Service Description document in response to a GET request. Here is an example of an Service Description document.

<?xml version="1.0" encoding='utf-8'?>
<service version="0.3" xmlns="http://purl.org/atom/ns#">
  <workspace title="Main Site" > 
    <collection rel="entries" name="Entries" href="http://example.org/reilly/feed" />
    <collection rel="categories" name="Categories" href="http://example.org/reilly/cat" />
    <collection rel="templates" name="Templates" href="http://example.org/reilly/tmpl" />
    <collection rel="users" name="Users" href="http://example.org/reilly/users" />
    <collection rel="resource" name="Pictures" href="http://example.org/reilly/pic" />
  </workspace>
  <workspace title="b-links">
    <collection name="Entries" href="http://example.org/reilly/b/feed" />
    <collection rel="entries" name="Entries" href="http://example.org/reilly/feed" />
    <collection rel="http://example.net/booklist" name="Books" href="http://example.org/reilly/books" />
  </workspace>
</service>  

Allowed values for rel:

The default for the rel attribute is 'resource'.

Extensibility for 'rel' values is handled in the same manner as PaceFieldingLinks.

Each 'collection' element in <workspace> represents a single facet of the AtomAPI. While a site must fully support each facet they list in their Service Description document, a site does not need to support all the facets in this RFC. Additionally, new facets may be added either through vendor extension or follow-on RFCs.

Note that the example URIs given are not normative, nor are there any constraints on the URIs that can be specified. The "Entries" collection could just as easily have been:

http://dev.example.net/api?userid=reilly&action=create

3.X.1 Locating the Service Description

Move the HTML component of this into the auto-discovery spec.

The <link> element has been successful in finding RSS feeds and is appropriate to use here for discovering the location of the Service Description document. The <link> tag goes in the <head> section of an HTML page and is used to indicate a document relationship. For a similar example of using the link tag to discover a URI, refer to the usage of of the link tag for RSS Auto-Discovery. In this case the form of the link tag used to indicate the location of the comment URI is:

<link rel="service.introspection" type="application/atom+xml"

Where href should be set to the URI of the Service Description file. Applications looking for the Service Description file to need to parse out the headers of the web page and look for a link tag that has a relation rel of "service.introspection" and a mime-type of "application/atom+xml".

3.X.2 Request

The only method specified for the IntrospectionURI is GET.

3.X.3 Response

The response from a successful GET request to an IntrospectionURI is an Service Description document.

3.X.3.1 The 'atom:service' element

3.X.3.2 The 'atom:workspace' element

3.X.3.2 The 'atom:collection' element

Rationale

A file similar to this format existed in previous drafts of the AtomAPI. It was dropped because it appeared to add more complexity to the API. Unfortunately it was dropped before there was much real world experience with the API. Since then SixApart and Blogger have both implemented the AtomAPI and one of the first things they did was to create a file that was similar in spirit to the introspection file. With both TypePad and Blogger a single user may have more than one site they manage. A single point of access was needed that enumerated all the sites that a user in managing and also lists all the facets that the service supports. Both SixApart and Blogger chose to use the Atom feed format for their file, but it does have the problem that the 'sites' listed in the file are not cleanly delineated. Here for example is an example file from my TypePad account:

<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://purl.org/atom/ns#">
  <link xmlns="http://purl.org/atom/ns#" type="application/x.atom+xml" rel="service.post"
    href="http://www.typepad.com/t/atom/weblog/blog_id=16815" title="BitWorking"/>
  <link xmlns="http://purl.org/atom/ns#" type="application/x.atom+xml" rel="service.feed"
    href="http://www.typepad.com/t/atom/weblog/blog_id=16815" title="BitWorking"/>
  <link xmlns="http://purl.org/atom/ns#" type="application/x.atom+xml" rel="service.upload"
    href="http://www.typepad.com/t/atom/weblog/blog_id=16815/svc=upload" title="BitWorking"/>
  <link xmlns="http://purl.org/atom/ns#" type="application/x.atom+xml" rel="service.categories"
    href="http://www.typepad.com/t/atom/weblog/blog_id=16815/svc=categories" title="BitWorking"/>
  <link xmlns="http://purl.org/atom/ns#" type="application/x.atom+xml" rel="service.post"
    href="http://www.typepad.com/t/atom/weblog/blog_id=18065" title="links"/>
  <link xmlns="http://purl.org/atom/ns#" type="application/x.atom+xml" rel="service.feed"
    href="http://www.typepad.com/t/atom/weblog/blog_id=18065" title="links"/>
  <link xmlns="http://purl.org/atom/ns#" type="application/x.atom+xml" rel="service.upload"
    href="http://www.typepad.com/t/atom/weblog/blog_id=18065/svc=upload" title="links"/>
  <link xmlns="http://purl.org/atom/ns#" type="application/x.atom+xml" rel="service.categories"
    href="http://www.typepad.com/t/atom/weblog/blog_id=18065/svc=categories" title="links"/>
</feed>

Note that this represents two sites, the main site and my link log.

Impacts

This changes undocumented functionality already deployed in the field.

This document may change to reflect User Management capabilities, which may encompass multiple workspaces.

Notes

Updated to follow PaceServiceElement.

Updated to use the term 'document' instead of 'file'.

Updated to include detailed descriptions of the attributes and elements of the introspection document.

CategoryProposals

PaceCollectionSyntax