Abstract
Conduct introspection with link elements and use workspace documents to provide additional structure as needed.
Rationale
Link following is a valuable way to discover resources.
In some cases a site map or manifest type pattern is very useful but it seems wise to take a note from the Web (REST architecture) where link following is the overwhelmingly dominant pattern.
Using a combination of workspace documents (as described below) and link rels, we get the best of both worlds in a simple and consistent way.
(Note that I left out paging as it can be covered by another Pace)
Proposal
Replace section 1 with:
1. Introduction The Atom Publishing Protocol is an application-level protocol for publishing and editing Web resources using HTTP [RFC2616] and XML 1.0 [W3C.REC-xml-20040204]. The protocol provides facilities for discovering, creating, reading, updating and deleting resources.
Add to section 3:
edit link - an Atom, APP or HTML link element whose rel attribute value is 'edit' (See section 10.1) entrycollection link - an Atom, APP or HTML link element whose rel attribute value is 'entrycollection (See section 10.2) mediacollection link - an Atom APP or HTML link element whose rel attribute value is 'mediacollection' (See section 10.3) workspace link - an Atom APP or HTML link element whose rel attribute value is 'workspace' (See section 10.4) editable representation - an editable representation is one that actors MAY be allowed to edit.
Add a section before the current section 5
5. Discovering Resources
Atom, APP and HTML link elements are used to discover the IRIs and
other metadata of various resources.
Client Server
| |
| 1.) GET |
|------------------------------->|
| |
| 2.) 200 OK, Hypertext |
|<-------------------------------|
| |
1. The client sends a GET request to a known IRI.
2. The server responds with an Atom, APP or HTML document containing
the IRIs and other metadata of various resources.
The methods of identifying the IRIs of resources are detailed in
sections 5.1 - 5.4.
5.1 Collections
The IRIs of Collections (See section 8) are found in the href attributes of
entrycollection links and mediacollection links (see section 3).
5.2 Entries
The IRI of the source (editable) Atom Entry Document representation
can be found in the href attribute of an edit link (see section 3).
The IRIs of other (derived) representations can be found in the
href attributes of alternate links.
5.3 Media
The IRI of an editable representation that may be of any media type
can be found in the src attribute of an atom content element.
5.4 Workspaces
The IRIs of Workspace Documents (see section 7) can be found in the
href attributes of workspace links (see section 3). The purpose of
such documents is simply to organize the discovery of resources.
Drop the current 5.1 and 5.4 from Protocol Operations.
Rename "Protocol Operations" to "CRUD Operations".
(Now we have "Resource Discovery" and "CRUD Operations")
Replace section 7 with:
7. Workspace Documents
7.1 Introduction
For authoring to commence, a client needs to first discover the
capabilities and locations of of various resources. These
are found in various links elements. (See Section 5)
In order to organize these links in various ways, such as when
creating a map of some or all of the collections provided by a
service, the Workspace Document can be used.
7.2 Example
<?xml version="1.0" encoding='utf-8'?>
<workspace title="Blogging Service" xmlns="http://purl.org/atom/app#">
<workspace title="Main Site" >
<link
rel="entrycollection"
title="My Blog Entries"
href="http://example.org/reilly/main" />
<link
rel="mediacollection"
title="Pictures"
href="http://example.org/reilly/pic" />
</workspace>
<workspace title="Side Bar Blog">
<link
rel="entrycollection"
title="Remaindered Links"
href="http://example.org/reilly/list" />
</workspace>
</workspace>
This Workspace Document describes a parent workspace and two child workspaces.
The first, called 'Main Site', has two collections called 'My Blog Entries' and
'Pictures' whose IRIs are 'http://example.org/reilly/main' and
'http://example.org/reilly/pic' respectively. 'My Blog Entries' is
an Entry collection and 'Pictures' is a Media collection. Entry and
Media collections are discussed in Section 7.3.4.
The second workspace is called 'Side Bar Blog' and has a single
collection called 'Remaindered Links' whose collection IRI is
'http://example.org/reilly/list'. 'Remaindered Links' is an Entry
collection.
Workspace documents are identified with the "application/
atomserv+xml" media type (see Section 14).
While a workspace document allows multiple workspaces, and workspace
nesting there is no requirement that a service support multiple workspaces
or nesting. In addition, links to a given resource MAY appear in more than
one workspace.
7.3 Element Definitions
7.3.1 The 'app:workspace' Element
The root of a workspace document is the app:workspace element.
namespace app = "http://purl.org/atom/app#"
start = appWorkspace
The "app:workspace" element can contain itself recursively in order to
express a hierarchical structure. The "app:workspace" element MAY
contain app:workspace or app:link elements.
appWorkspace =
element app:workspace {
appCommonAttributes,
attribute title { text },
( appWorkspace*
& appLink*
& extensionElement* )
}
7.3.1.1 The 'title' Attribute
The app:workspace element MUST contain a 'title' attribute, which
conveys a human-readable name for the workspace. This attribute is
Language-Sensitive.
7.3.2 The 'app:link' Element
The app:link element is identical to the Atom link element.
Remove references to "Introspection Document" from sections 8 and 9.
Add these to section 10
10.2 The 'entrycollection' Link Relation This specification adds the value "entrycollection" to the Registry of Link Relations. The value of "entrycollection" signifies that the IRI in the value of the href attribute is the IRI of an entry collection resource as described in section 8. 10.3 The 'mediacollection' Link Relation This specification adds the value "mediacollection" to the Registry of Link Relations. The value of "mediacollection" signifies that the IRI in the value of the href attribute is the IRI of an media collection resource as described in section 8. 10.4 The 'workspace' Link Relation This specification adds the value "workspace" to the Registry of Link Relations. The value of "workspace" signifies that the IRI in the value of the href attribute is the IRI of a APP workspace resource as described in section 7.
References
Impacts
draft06
