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
-
Should we create new atom:service, atom:workspace, and atom:collection elements for the introspection format, or can atom:feed and atom:entry fill those roles?
-
Is "service" an appropriate name?
-
What services does introspection need to expose? (See PaceServiceElement for a possible enumeration).
-
What resources should be introspectable? Sites? Feeds? Individual users of a site?
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:
-
entries
-
categories
-
templates
-
users
-
resource ( default )
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"
-
href="url goes here" title="AtomAPI">
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
-
The "atom:service" element is the document (i.e., top-level) element of an Service Description Document, acting as a container for service data associated with possibly multiple workspaces. Its only child elements MUST be one or more atom:workspace elements.
The "atom:service" element MUST have a single attribute 'version' whose content indicates the version of the Atom specification that the feed conforms to. The content of this attribute is unstructured text.
The version identifier for this specification is "1.0".
3.X.3.2 The 'atom:workspace' element
-
The "atom:workspace" element contains information elements about the collections of resources available for editing. The only children of "atom:workspace" MUST be one or more "atom:collection" elements.
The "atom:workspace" element MUST have a single attribute 'title' whose content MUST NOT be empty and which is a human-readable name for the workspace.
3.X.3.2 The 'atom:collection' element
-
The "atom:collection" element describes various typed groups of resources available for editing or adding to.
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.
