All,

There's been some discussion about how the People RESTful API operates in the context of Friends, in particular: 1. When you don't actually have the power to just insert something into 'your' @friends collection, because friending requires double opt-in from both parties; and 2. When the records you get in @friends are actually information provided by the social network on behalf of your friends, that is, the records represent _connections_ to a person in the network rather than a static collection of fields.

The spec is somewhat ambiguous on these points, because it wants to support all kinds of containers, not just those with constraints 1 and 2. However, for containers with those constraints, it makes a lot of sense to document how the RESTful API is supposed to work. I'd like to propose a clarification to the spec text that would be a version of the following; comments and suggestions welcomed.

------SPEC TEXT---- The RESTful API supports containers where friending involves an invitation process and where friend records actually represent live, filtered views of other people's profiles; in fact this is the common case today. This note describes the intended semantics of the RESTful API in these cases.

To invite a friend, you POST a sufficiently identifying representation of the friend to your own @friends group. Containers SHOULD allow invitation with nothing more than an email (emails are universally unique). Containers MAY allow invitation via other attributes, for example, OpenID, user/login information, telephone number, or address. In this case a client is asking the container to create a connection (represented as a Person) given the submitted data; the container may nor may not honor the request, and if it honors the request, it MAY not do so immediately.

If it _does_ honor the request immediately, it MUST respond with a 201 Created response and return a Location: header pointing to the newly created connection. Note that the container MAY modify any or all fields submitted when creating the connection; for example, it MAY modify the email address to be the new/default email address specified by the other user.

If it does not honor the request, but must start additional workflow, it MUST respond with a 202 Accepted response and a Location: header pointing to where the record will be once the workflow successfully completes. Workflow might include an opt-in from the other party, moderation or rate limiting, or any other process that must complete asynchronously to the RESTful API. The client can check the URI returned, if necessary, to see if the workflow has completed; it SHOULD respond with a 404 Not Found until the workflow is completed, after which it SHOULD respond with a 200.

DELETEing a Person resource which is actually a connection simply removes the connection (unilaterally).

PUTting modified data to a Person resource which is a connection may or may not be allowed, depending on the container. For example, some containers may allow people to assign useful nicknames to their connections (not visible to the connections), or augment the available information with additional data. However, containers are not required to support this and MAY provide only a read-only view of the data, in which case PUT SHOULD result in a 405 Method Not Allowed error.

Note that PUTting to the @self record for the current user allow modification of one's own profile data. Containers MAY also allow DELETE to let a user remove themselves from the network entirely, but are not required to do so; again, if this method is not suported, 405 Method Not Allowed is the appropriate response.

Some networks do not require double opt in, but provide connection semantics if there _is_ double opt in. (The AIM IM network, if represented in OpenSocial, would be an example of this; you are free to add anyone to your buddy list given their screen name, but they do not necessarily get a notification of this, and you do not get any presence information or other updates unless they also add you as a buddy.) In this case, the POST would always return a 201 Created, but the record would be 'static' until and unless the person on the other end does the reverse operation.

Conflicts: In some cases, attempting to add a second friend may have a primary key conflict with an existing friend. In this case, containers SHOULD return a 409 Conflict status and a Location: header pointing at the other (conflicting) resource. For example, if a person with the primary email john...@example.org already exists, an attempt to POST a resource with an email john...@example.org MAY fail with a 409 response. Containers MAY define their own rules for conflicting keys and MAY not attempt any conflict detection at all, simply assigning each new record a new unique internal identifier.

----END OF SPEC TEXT---