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