OpenSocial Messaging API

[Paul Lindner]

Hi,

Here is a draft of a proposed way to implement OpenSocial Messaging APIs.  I'd like to collaborate with others that care about this.  I also need to create a corresponding JS API for all this.  I have a version of shindig that implements some of these features that is based on the patches in SHINDIG-629 and SHINDIG-646.  The SocialSite implementation also has much of these same features too.  Some notes on this are available here:  http://wikis.glassfish.org/socialsite/Wiki.jsp?page=FinalizeRESTAPI

OpenSocial Messaging Proposal

version 1, 2008-11-07

Most Social Networks offer some way of messaging and communication between users.  The current spec defines a number of JavaScript APIs to request sending a message.  However there is not a corresponding messaging API to implement these.  Each container has done this in separate ways.  This proposal attempts to extend the current messaging model to support API access for existing OpenSocial 0.8.1 message functionality while adding full read/write REST and Javascript capabilities.

Modeling Changes

Messages

The current Message Model offers the following fields:

BODY

TITLE

TYPE (one of email, notification, privateMessage, publicMessage)

This is sufficient for a message submission API, it is not sufficient for a full API.  The following fields should be added to the Message model:

ID (unique ID for this message)

RECIPIENTS (array of person IDs)

SENDER (id of person who sent the message)

TIME_SENT (time message was sent)

PARENT_ID (Message ID, use for threaded comments/messages)

STATUS (NEW, DELETED, TRASH?, SPAM?)

APP_URL Identifies the application that generated this message

Message Groups

All messaging systems have a way of grouping messages.  Some group by type, some by types of users.  Each container is different.  To accommodate this we provide a new model, the MessageGroup

  ID unique id for this message group

  NAME name for this message group

  TOTAL total number of messages in this group

  UNREAD number of unread messages in this group

  TYPE optional, defines a constrained group that contains only certain message types

There are two 'special' message group Ids -- @all is all messages for the user, and @outbox is a special message group used for posting messages.

"Requests" / "Invites" / "Share"

Many sites have the capability to 'invite', 'share', or 'request' certain things.  This is not defined yet.

RPC/REST Operations

General Layout of messaging REST URLs looks like this:

  messages/{userId}/{messageGroupId}/{messageId}

UserId can be a static value or @me

Operations on Message Groups

GET messages/{userId}   return collection of Message Groups

POST messages/{userId}   Create a new Message Group

DELETE messages/{userId}/{messageGroupId}

PUT messages/{userId}/{messageGroupId} modify message group parameters (name)

All standard Collection Options work on this feed.  startWith, count, sortBy, and Filter mechanisms.

Operations on Messages

GET messages/{userId}/{messageGroupId} return specified collection of Messages

GET messages/{userId}/@all return all messages

All standard Collection Options work here.  startWith, count, etc.  Especially useful are the following:

   All messages of type -- filterBy=type, filterOp=equals, filterValue={notifications, privateMessage, ...}

   Threaded comments -- sortBy=parentId

To create a new message:

POST messages/{userId}/@outbox recipients must be specified.

Moving a message to a group:

POST messages/{userId}/{messageGroupId} add message to this message group.

GET messages/{userId}/{messageGroup}/{messageId} retrieve singular message

PUT messages/{userId}/{messageGroup}/{messageId}  Modify message with changed fields

POST messages/{userId}/{messageGroup}/{messageId} same as posting a message with parentId=messageId

DELETE messages/{userId}/{messageGroup}/{messageId}  delete message

Paul Lindner

plin...@hi5.com

[bobby]

> The current Message Model offers the following fields:
>
> BODY
> TITLE
> TYPE (one of email, notification, privateMessage, publicMessage)
>
> This is sufficient for a message submission API, it is not sufficient  
> for a full API.  The following fields should be added to the Message  
> model:
>
> ID (unique ID for this message)
> RECIPIENTS (array of person IDs)
> SENDER (id of person who sent the message)
> TIME_SENT (time message was sent)
>
> PARENT_ID (Message ID, use for threaded comments/messages)
> STATUS (NEW, DELETED, TRASH?, SPAM?)
> APP_URL Identifies the application that generated this message

There's a similar proposal here (for the api and not specifically the
implementation):
http://docs.google.com/View?docid=dfjz793x_187gm3prnch

...but some of the fields are different. You may want to bring these
up on the discussion for this proposal (which is mine, based on the
same SocialSite page that you link to):

http://groups.google.com/group/opensocial-and-gadgets-spec/browse_thread/thread/7c17d133e9f63ee6?hl=en

Cheers,
Bobby

[Paul Lindner]

Hi Bobby,

I did not see your previous proposal to the list. My apologies. I've
been working on a separate implementation, had seen some of the
submitted patches and started reconciling.

I'd like to work together to hammer out something that fits all of our
requirements. I need summary information about message groupings at
the very least. Can we merge these together?

Paul Lindner
plin...@hi5.com

[Scott Seely]

For tracking purposes, it might be better to continue this on the
original thread:
http://groups.google.com/group/opensocial-and-gadgets-spec/browse_thread
/thread/7c17d133e9f63ee6/3e9282170dfde3a8?hl=en&lnk=gst&q=messaging+chan
ges#3e9282170dfde3a8

thanks!

[bobby]

> I did not see your previous proposal to the list.  My apologies.

No problem! Sure, we should try to merge the proposals wherever we
can, and it would be good to get Ropu's opinion since I built on his
work already. Will move over to the other thread as Scott suggests;
can you send something to that thread with a link to your proposal so
that the other folks will get a chance to see it.

Cheers,
Bobby

[Lane LiaBraaten]

FYI - I created a page on the wiki to summarize/track these proposals.  Since this is a merging of two proposals, I think the wiki will be especially useful here.

http://wiki.opensocial.org/index.php?title=Messaging_API_Changes

-Lane

[Paul Lindner]

Okay, I'll merge the two proposals.

I'm also aligning with the AtomPub threading http://www.ietf.org/rfc/rfc4685.txt

Paul Lindner

plin...@hi5.com