[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
PacePaperTrail (Was Re: tests removed from APP test suite)
This Pace attempts to clarify the ambiguities brought
up in this discussion thread:
http://www.intertwingly.net/wiki/pie/PacePaperTrail
#pragma section-numbers off
== 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 that contains the Member URI of the
newly created resource.
Note that creating a resource in a collection may in fact create
more than one resource and those resources may be accessed by many
different URIs, all of which has no impact on the fact that only
one Member URI is added to the collection.
}}}
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, all of which 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
On 3/29/06, Joe Gregorio <joe.gregorio@xxxxxxxxx> wrote:
> On 3/29/06, James M Snell <jasnell@xxxxxxxxx> wrote:
> >
> >
> > Sam Ruby wrote:
> > >[snip]
> > > 1) Is it possible for implementations to outright fail to operate as
> > > epxected if this constraint is not satisfied?
> > >
> > > If NO, consider MAY. Avoid making additional judgement calls. Accept
> > > the additional complexity and interopability issues that this creates.
> > >
> > > If YES, ask yourself if there still are reasons why an implementation
> > > might rightfully and willfully chose to ignore this. If so, chose
> > > SHOULD. Else chose MUST.
> > >
> >
> > The main consideration for me on this are post-only, moderated an
> > access-controlled collections. In such cases, server implementations
> > should be able to choose not to return a Location header or have the
> > newly posted entry appear in any feed that a client can see. That said,
> > it should likely be tied to the type of response.
>
> A resource is a resource, if the server created it there shouldn't be
> a problem with returning a Location: header. The server can enforce
> the read-only nature of that resource using authentication. You
> aren't suggesting using security through obscurity, are you?
>
> >
> > If the server responds with a 201 Created, then I'd likely agree that
> > the response ought to contain a Location header.
>
> SHOULD
>
> > If the server responds with a 202 Accepted, then the response shouldn't
> > contain a Location header.
>
> MAY NOT
>
> > Regarding whether or not the entry should appear in the feed is a
> > separate question. If the response is 201 Created, I would say it
> > likely SHOULD be listed in the feed *that the posting client sees*, but
> > there are conceivable reasons why it would not (e.g. read permissions
> > not currently granted to the client requesting the feed, the entry may
> > be awaiting moderation, etc). If the response is 202 Accepted, I would
> > say that it SHOULD NOT appear in the feed, at least not right away.
>
> You are necessarily constrained to talking about the
> 'posting client' only since we are talking about
> a URI returned in the Location: header.
>
> > Consider the following:
> >
> > In our implementation, we have an entry collection to which all users
> > can POST new entries. Clients can only view entries for which they are
> > the owner (original creator) or have been granted permission to read.
> > When I post an entry to the collection, and Sam subsequently reads the
> > feed, his view of the feed will not contain the entry I posted. Is that
> > an error?
>
> No, see above about the Location: header.
>
> Now a 202 does not indicate a successful creation, only
> that the server is in the process of working on it, so I don't
> see any of the above discussion contradicting anything
> in -08, but I do see a need to add a clarifying sentence or
> two to Section 8.1:
>
> """If a POST to a collection results in a member resource being
> successfully created then an entry SHOULD appear
> in the collection feed that has a link/@rel='edit' with an
> @href that matches the URI returned in the Location: header.
> Some reasons that an entry might not appear in a
> collection feed include: the member may have been deleted between
> creation and the time the client retreives the collection
> document, or the collection may represent a blind dropbox
> where collection members may be created by one groupd of
> people but can only be read by a third party, for example a
> collection for students to POST homework results to that can only
> be read by the teacher.
> """
>
> -joe
>
> --
> Joe Gregorio http://bitworking.org
>
--
Joe Gregorio http://bitworking.org