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.