UserPreferences

PacePaperTrail


Abstract

APP-08 is currently ambiguous about the 'edit' URI for member resources and this makes it hard for clients to follow the "paper trail" from creation of an entry, to it's appearance in the collection, to its removal from the collection. This Pace adds verbage to make the paper trail clear, by strengthening the term Member URI and further making the Member URI invariant between the Location: header and its appearance in the collection feeds.

Status

Open (JoeGregorio)

Rationale

Proposal

In Section 5.2 Creating a Resource

Replace

   2. If the Member resource was created successfully, the server responds with a status code of 201 and a Location: header that contains the URI of the newly created resource.
With
   2. If the Member resource was created successfully, the response MUST include a Location: header containing the Member URI 
      of the newly created resource. Note that creating a resource in a collection may result in the creation  more than 
      one resource and those resources may be accessible by  URIs other than the Member URI. Even though multiple resources
      may have been created, only one Member URI is added to the collection. How such additional resources are 
      discovered is beyond the scope of this document.

In 5.3 Editing a Resource

Replace

Once a resource has been created and its URI is known, that URI may be used to retrieve, update, and delete the resource.
With
Once a resource has been created and its Member URI is known that URI may be used to retrieve, update, and delete the resource.

To Section 5.3.3 Deleting a Resource change

2. Upon the successful deletion of the resource the server responds with a status code of 200.

to read

2. Upon the successful deletion of the resource the Member URI no longer appears in the collection. Note
   that it is possible that mulitple resources were created when this member was POSTed to the collection
   and those resources may still exist and be accessible via other URIs following the DELETE on the
   Member URI. How such additional resources are deleted is beyond the scope of this document.

To the first paragraph in Section 8.1 add

  The Member URI returned in the Location: header MUST be the same URI 
  as the Member URI that appears in the collection.
  Some reasons that an entry might not appear in a
  collection include: the member may have been deleted between
  the time of creation and the time the client retreives the collection
  document(s), additionally the content of the collection's feed can
  vary based on aspects of the client request, 
  including, but not limited to, authentication credentials.

Section 9 Listing Collections

Change

Collection resources MUST provide representations in the form of Atom Feed documents. Each entry in 
the Feed Document MUST have an atom:link element with a relation of "edit" (See Section 10.1).
To
Collection resources MUST provide representations in the form of Atom Feed documents. Each entry in 
the Feed Document MUST have an atom:link element with a relation of "edit" (See Section 10.1). For
an Entry Collection the URI in that atom:link element is the entries Member URI. For Media Collections
the Member URI appears as the value of the "src" attribute of the atom:content element.

A resource is considered a member of a collection if it has a Member URI that appears
in a collection, that is, the URI appears as a Member URI in one of the paged feeds
for a collection.

Impacts

Notes


CategoryProposals