11. Messaging (Optional)

A social network service may optionally expose a mechanism for sending short messages between users. The functionality and policies are parallel to those of the JS API's requestSendMessage.

Discovery

If a container supports messaging, it advertises a "messages" Service in its discovery document: 

<Service>
  <Type>http://ns.opensocial.org/messages/0.8</Type>
  <os:URI-Template>http://api.example.org/messages/{guid}/outbox/{msgid}</os:URI-Template>
</Service>

Semantics

To create a message and place it in a queue, a client POSTs a message to an 'outbox' collection resource discovered from the XRDS document: 

POST /messages/{guid}/outbox/{msgid}

The outbox is owned by the source user. Placing a message in the outbox requests that the message be delivered to one or more recipients. Containers are free to filter or alter the message according to their own policies (such as security or rate limiting policies).


Recipients can request messages by requesting them from their 'inbox' collection for received messages or 'outbox' collection for sent messages. If {msgid} is omitted, all messages are returned.

GET /messages/{guid}/inbox/{msgid}
GET /messages/{guid}/outbox/{msgid}

Recipients can remove messages by sending a DELETE request to either the inbox or outbox. A message may also be updated with a PUT request (i.e., marking the messages as 'read'). In a DELETE or PUT request, {msgid} is required.


A Message example follows. For brevity, details of the 'sender' field, an OpenSocial Person, are ommitted. These are specified in the Restful Protocol specification at http://www.opensocial.org/Technical-Resources/opensocial-spec-v081/restful-protocol


application/json representation:


{
   "id" : "http://example.org/inbox/message/{msgid}",
   "recipients" : ["example.org:AD38B3886625AAF", "example.org:997638BAA6F25AD"],
   "sender" : "{ "id" : ... }",
   "title" : "You have a new messge from Joe",
   "titleId" : "541141091700",
   "body" : "Short message from Joe to some friend\/s",
   "bodyId" : "5491155811231",  
   "type" : "PRIVATE_MESSAGE",
   "status" : "UNREAD",
   "data" : "..."
}

application/xml representation:

<message xmlns="http://ns.opensocial.org/2008/opensocial">
  <id>http://example.org/inbox/message/{msgid}</id>
  <recipient>example.org:AD38B3886625AAF</recipient>
  <recipient>example.org:997638BAA6F25AD</recipient>
  <sender>
    <person>...</person>
  </sender>
  <title>You have a new messge from Joe</title>
  <titleId>541141091700</titleId>
  <updated>2008-09-29T23:35:37.266Z</updated>
  <body>Short message from Joe to some friend\/s</body>
  <bodyId>5491155811231</bodyId>
  <type>PRIVATE_MESSAGE</type>
  <status>UNREAD</status>
  <data>...</data>
</message>


application/atom+xml representation:

<entry xmlns="http://www.w3.org/2005/Atom" xmlns:osapi="http://opensocial.org/2008/opensocialapi">
<osapi:recipient>example.org:AD38B3886625AAF</osapi:recipient>
<osapi:recipient>example.org:997638BAA6F25AD</osapi:recipient>
<sender><person>...</person></sender>
 <title>You have a new messge from Joe</title>
<id>http://example.org/inbox/message/{msgid}</id>
<link rel="alternate" href="http://app.example.org/inbox/message/{msgid}"/>
<content>Short message from Joe to some friend/s</content>
<status>UNREAD</status>
<data>...</data>
</entry>

The {msgid} is client generated and SHOULD be globally unique. If a client does not care about failure cases, it can alternatively use a standard AtomPub POST to /messages/{source-uid}/outbox and leave generation of the ID to the container. In either case, the response is 201 Created on success.

If not supported, the response code should be 403 Not Implemented.

Typically a container would choose to only allow a POST to an outbox where the {guid} equals the requestor id, but this is a container security policy decision. Containers may choose to allow messaging only between friends or user other heuristics to prevent spam.


The 'sender' field in the message representations is only needed when receiving a message with a GET request. It is not required when POSTING a new message as this information is represented by the {guid}. Using a Person for the sender field allows a gadget to present meaningful information about the message sender without requiring a separate request for this information.


The 'data' field is used for information specific to the gadget that is sending or displaying the message. It may be omitted in most messages. An example is a message from a user asking to join a group. In the received message to the group's owner(s), the 'data' field could contain the JSON or XML representation of an OpenSocial Group.