UserPreferences

PaceLinksAndWorkspaces


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

Notes


CategoryProposals