REST write semantics -- a lot of work to be done
David Primmer
endpoints in the REST api are writable and what those write semantics
are. A quick illustration:
/people/{guid}/@friends -- Collection of all friends of user
Which operations should this collection support? The spec usually says
nothing explicit about write ops but it actually is not silent on this
"friending" matter:
"Friends may be added by POSTing to the appropriate collection (e.g.,
/people/{guid}/@friends). Containers MAY require a dual opt-in
process before the friend record appears in the collection, and in
this case SHOULD return a 202 Accepted response, indicating that the
request is 'in flight' and may or may not be ultimately successful."
Do we write paragraphs like this for all the endpoints? The spec has
tried to stay out of compelling containers to behave a certain way and
this has been easy when we're talking about read access. But write is
another matter. I'm further trouble by the fact that the endpoints are
just 'examples' according to the spec and the container could choose
to implement write functions and side effects in any way they choose.
Maybe this is just a discussion for shindig...
My understanding normal ATOM Pub would be that you would post the full
representation of the user that you want to add to a collection.
You're not creating a friend link, you're adding an actual person
resource. But since the person already exists in the container, in
this case we need a minimum of what is required to create a new friend
connection. Where is this specified? Is this the same as the minimum
fields in the JS person spec or is it just the guid of the person.
Many many questions. The way I see the spec functioning is that you'd
post a guid to a friends collection and if there is no dual opt-in the
response would be a feed with the full representation of the friend's
profile.
However, why not post a friend connection representation to a
friendship collection? Isn't that link the real resource instead of
the container that displays people with those connections?
The spec seems to point in directions where it would be possible to
extend the "friending" mechanism of the container to the rest api. Is
anyone worried that this over-specifies behavior?
Other collections are somewhat easier: /people/{guid}/@all/ collection
which seems like it could be fully writeable by the guid person and it
functions like a private collection 'contact list'-like collection.
Activities is the same. there could be a general rule that the
aggregating feeds like "activities of my friends" are not writable.
Rules for all these collections need to get fleshed out:
People - friends and groups complicate matters.
Activities - same as people
Groups - pretty easy at first glance.
AppData - should be no questions here
Messages - big ? here.
Paul Linder added another wrinkle that goes beyond these issues to
partial updates and what are the rules for changing one bit of info in
a profile like "status". This is important but I feel like we need to
work out the collection issues as well.
davep
John Panzer
The idea is that a container decides what is allowed, and advertises what's allowed in the Allow: header for each resource (collection or individual person/activity/etc). These are standard HTTP methods, POST PUT DELETE GET HEAD... For collections we adopt the Atom semantics (POST to add). Non-collections use GET PUT DELETE for what you'd expect.
The paragraph below was to highlight the way in which a collection can implement dual opt-in semantics (it doesn't have to accept or reject a suggested addition, but can take it under advisement and/or modify the resulting resource, again AtomPub style semantics but with our own syntax).
At least, that's the original intent.
David Primmer
implementation of the spec it needs to make these decisions and my
attempts to implement led me to ask these questions. My intent in
posting it here was to see if any of these decisions could be spec'd
out as it seems that would make interop easier. But if you say it's
all to be described by the service then I suppose we could try it in
the discovery doc.
However, my question below about how complete a resource a client is
expected to post is valid isn't it? Atom has requirements for the
minimum that can be posted to make a new resource but what about json
bodies? Do we use Atom as a guide or the JS data schema? I think this
should be mentioned and the fields listed.
Here it is put another way:
AtomPub assumes Atom Docs will be POSTed and Atom Docs have schema
requirements: title, author, id and updated. Any of these can be
modified by the server when creating the actual resource. If it's not
an Atom doc, AtomPub assumes it's a Media type, has no schema
requirements and can accept it or return a 415 ("Unsupported Media
Type"). How does this translate to a dual format server? What is the
minimum schema for a JSON doc?
And I'm afraid I must beat on the whole friends link thing some more.
It is really blurring the line between PUT, modification of a known
resource and POSTing a new resource. Don't the semantics depend on
what the resources are in the collection? Since the resources returned
from the friends feeds are person objects, it's a little harder to see
how they're writable. If you want to just create a friend
relationship, do you need to post a representation complete enough to
create the resource? If we're defining the semantics of the
collections and the wire formats why wouldn't this also be defined?
I don't know if it's too late now, and you probably thought of this,
but could we solve the ambiguity with using links? Editing a person
and setting a link rel="friend" pointing to the id of the person to
friend?
davep
On Thu, May 29, 2008 at 5:54 PM, John Panzer <jpa...@google.com> wrote:
> The spec references the semantics of Atom collections and resources, which
> should probably be made more explicit.
>
> The idea is that a container decides what is allowed, and advertises what's
> allowed in the Allow: header for each resource (collection or individual
> person/activity/etc). These are standard HTTP methods, POST PUT DELETE GET
> HEAD... For collections we adopt the Atom semantics (POST to add).
> Non-collections use GET PUT DELETE for what you'd expect.
>
I know there's no representation of showing friends as links right now
but what about extending the person object with links to friends? So
what about allowing PUT to a person with a link rel="friend" pointing
to the id of the person they want to friend?
Paul Walker
You're bringing a lot of questions to the table that are simply
unanswered at this point according to the spec.
On POST/PUT of a resource, my thinking has always been that a POST of a
new resource to a collection or list is appropriate. However, a PUT is
also appropriate if the URI of that new resource is known to the client
before the PUT. However, I don't think we have defined a resource for a
"friendship" yet. If additional information can be provided to define
that resource on the POST to the collection, it may (perhaps through
addl' params on the URI) or may not be present on the GET, but I agree
that the minimal information required should.
In general, I think what is needed is
1) a schema to define the xml nodes that are not atom centric.
2) example URIs, HTTP methods and responses and potential status codes
given implementation details of the OS Provider -- not everyone is going
to support breaking friendships ;-).
Let's work together to do just that.
~Paul