RESTful API addition: send message

[John Panzer]

As Cassie pointed out, the standard JS API already has a requestSendMessage method (http://code.google.com/apis/opensocial/docs/0.7/reference/opensocial.html#requestSendMessage).  Servers are free to respond with a NOT_IMPLEMENTED status if they don't want to implement messaging.

I'd like to propose adding this to the RESTful spec as well, so that clients can request that messages be sent without having to run from inside a gadget.  While there are certainly security implications to opening up a messaging API, I think that the delta to adding this to the REST API is small, given that it's already present for JS gadgets.  It will probably require some trust model based on the verified oauth_consumer_key (=app id).  The major differences between the two situations are:

(1) In the RESTful case, it's not as easy to confirm with the user prior to sending messages.  (It's still possible, by using asynchronous communication and putting app messages in a queue until the user approves them.)
(2) The user may not have installed the app prior to it calling the API, unlike the gadget case.  However, the container can still apply the same rule (if user has the app, let the RESTful call through; else, fall back to explicit whitelists and/or moderation queue).

And of course a server which doesn't want to deal with this can simply return NOT_IMPLEMENTED for the RESTful call only.

So, proposal:

The JS call looks like this:

requestSendMessage(recipients, message, opt_callback)

The RESTful operation would look like this:

PUT /messages/{uid}/outbox/{msgid}
Content-Type: application/atom+xml

<entry xmlns="http://www.w3.org/2005/Atom" xmlns:osapi="http://opensocial.org/2008/opensocialapi">
  <osapi:recipient>orkut.com:AD38B3886625AAF</osapi:recipient>
  <osapi:recipient>orkut.com:997638BAA6F25AD</osapi:recipient>
  <title>You have an invitation</title>
  <id>{msgid}</id>
  <link rel="alternate" href="http://app.example.org/invites/{msgid}"/>
  <content>Click <a href="http://app.example.org/invites/{msgid}">here</a> to review your invitation.</content>
</entry>

...

201 Created
Location: /messages/{uid}/outbox/{msgid}

<entry xmlns="http://www.w3.org/2005/Atom">
  <title>You have an invitation</title>
  <id>{msgid}</id>
  <link rel="alternate" href="http://app.example.org/invites/{msgid}"/>
  <content>Click <a href="http://app.example.org/invites/{msgid}">here</a> to review your invitation.</content>
</entry>

Other common response codes: 203 Accepted, 401 Unauthorized, 403 Forbidden (NOT_IMPLEMENTED)

The server can rewrite the message to its own specifications, drop fields, sanitize HTML, etc.  It reflects the result back to the client so the client can find out how its text got munged (if it cares).  The interfaces uses a PUT with a client-generated msgid to allow for safe retries; a second PUT on top of an existing one is ignored, so a timeout can always be retried again (within a reasonable time frame, say 1 day) without sending multiple messages.

The semantics are otherwise exactly the same as whatever requestSendMessage does on that container.

The JSON data representation follows the same rules as for activities (see RESTful spec).

Thoughts?

[Nat Brown (ilike.com)]

+1. this would be ideal. i personally like the {msgid} semantics which
we could use to ensure important messages are retried, though i can
imagine some containers not wanting to go through the trouble to
implement this part -- should probably be optional.
additional error response "413 Request Entity Too Large" if an html
message is too big for some reason would be useful.
n@

On Apr 15, 10:13 am, "John Panzer" <jpan...@google.com> wrote:
> As Cassie pointed out, the standard JS API already has a requestSendMessage

> method (http://code.google.com/apis/opensocial/docs/0.7/reference/opensocial....).

> Servers are free to respond with a NOT_IMPLEMENTED status if they don't want
> to implement messaging.
>
> I'd like to propose adding this to the RESTful spec as well, so that clients
> can request that messages be sent without having to run from inside a
> gadget. While there are certainly security implications to opening up a
> messaging API, I think that the delta to adding this to the REST API is
> small, given that it's already present for JS gadgets. It will probably
> require some trust model based on the verified oauth_consumer_key (=app
> id). The major differences between the two situations are:
>
> (1) In the RESTful case, it's not as easy to confirm with the user prior to
> sending messages. (It's still possible, by using asynchronous communication
> and putting app messages in a queue until the user approves them.)
> (2) The user may not have installed the app prior to it calling the API,
> unlike the gadget case. However, the container can still apply the same
> rule (if user has the app, let the RESTful call through; else, fall back to
> explicit whitelists and/or moderation queue).
>
> And of course a server which doesn't want to deal with this can simply
> return NOT_IMPLEMENTED for the RESTful call only.
>
> So, proposal:
>
> The JS call looks like this:
>

> *requestSendMessage*(recipients, message, opt_callback)

[Paul Walker]

@MySpace where we are treading carefully with this for the server to server requests

 

Sending a message on behalf of a user:

-          The user must grant the application specific permission to do so and be able to readily revoke it

-          Quotas applied to apps even so

 

Sending a message to a user

-          The user must have the app installed and/or ( ;-) ) grant permission to the app to do so and be able to readily revoke it.

-          Quotas unnecessary obviously

 

~Paul

[John Panzer]

There have been a couple of requests off-list for this functionality
from containers and I'd like to add it to the RESTful spec (as an
optional feature). The caveats below are good ones that I'll add in
as best practices for containers to follow. Could we get some more
+1's on this thread?

On Apr 17, 1:40 am, "Paul Walker" <pwal...@myspace.com> wrote:
> @MySpace where we are treading carefully with this for the server to
> server requests
>
> Sending a message on behalf of a user:
>
> - The user must grant the application specific permission to do
> so and be able to readily revoke it
>
> - Quotas applied to apps even so
>
> Sending a message to a user
>
> - The user must have the app installed and/or ( ;-) ) grant
> permission to the app to do so and be able to readily revoke it.
>
> - Quotas unnecessary obviously
>
> ~Paul
>
> From: opensocial-an...@googlegroups.com
> [mailto:opensocial-an...@googlegroups.com] On Behalf Of John
> Panzer
> Sent: Tuesday, April 15, 2008 10:13 AM
> To: opensocial-an...@googlegroups.com
> Subject: RESTful API addition: send message
>
> As Cassie pointed out, the standard JS API already has a
> requestSendMessage method
> (http://code.google.com/apis/opensocial/docs/0.7/reference/opensocial.ht

> ml#requestSendMessage). Servers are free to respond with a

> <http://app.example.org/invites/%7bmsgid%7d> "/>

> <content>Click <a href="http://app.example.org/invites/{msgid}

> <http://app.example.org/invites/%7bmsgid%7d> ">here</a> to review your

> invitation.</content>
> </entry>
>
> ...
>
> 201 Created
> Location: /messages/{uid}/outbox/{msgid}
>
> <entry xmlns="http://www.w3.org/2005/Atom">
> <title>You have an invitation</title>
> <id>{msgid}</id>
> <link rel="alternate" href="http://app.example.org/invites/{msgid}

> <http://app.example.org/invites/%7bmsgid%7d> "/>

> <content>Click <a href="http://app.example.org/invites/{msgid}

> <http://app.example.org/invites/%7bmsgid%7d> ">here</a> to review your

[Graham Spencer]

+1 -- lots of requests for this.

--g

[Lou Moore]

+1

>   <link rel="alternate" href="http://app.example.org/invites/{msgid} <http://app.example.org/invites/%7Bmsgid%7D>
> <http://app.example.org/invites/%7bmsgid%7d> "/>
>   <content>Click <a href="http://app.example.org/invites/{msgid} <http://app.example.org/invites/%7Bmsgid%7D>

> <http://app.example.org/invites/%7bmsgid%7d> ">here</a> to review your
> invitation.</content>
> </entry>
>
> ...
>
> 201 Created
> Location: /messages/{uid}/outbox/{msgid}
>
> <entry xmlns="http://www.w3.org/2005/Atom">
>   <title>You have an invitation</title>
>   <id>{msgid}</id>

>   <link rel="alternate" href="http://app.example.org/invites/{msgid} <http://app.example.org/invites/%7Bmsgid%7D>
> <http://app.example.org/invites/%7bmsgid%7d> "/>
>   <content>Click <a href="http://app.example.org/invites/{msgid} <http://app.example.org/invites/%7Bmsgid%7D>

[Dan Peterson]

+1  -- makes sense to have REST API functionally equiv to JS API

 

-Dan

[Zhen Wang]

+1 -- seems pretty useful

[Gary Helmling]

> The RESTful operation would look like this:
>
> PUT /messages/{uid}/outbox/{msgid}
> Content-Type: application/atom+xml
>
> <entry xmlns="http://www.w3.org/2005/Atom"
> xmlns:osapi="http://opensocial.org/2008/opensocialapi">
> <osapi:recipient>orkut.com:AD38B3886625AAF</osapi:recipient>
> <osapi:recipient>orkut.com:997638BAA6F25AD</osapi:recipient>
> <title>You have an invitation</title>
> <id>{msgid}</id>
> <link rel="alternate" href="http://app.example.org/invites/{msgid}
> <http://app.example.org/invites/%7bmsgid%7d> "/>
> <content>Click <a href="http://app.example.org/invites/{msgid}
> <http://app.example.org/invites/%7bmsgid%7d> ">here</a> to review your
> invitation.</content>
> </entry>

Sorry if I'm being slow here, but for the REST API, should the {msgid}
be supplied by the caller? Where is the {msgid} being generated?

If it is being generated by the caller, then the request body already
contains the Atom <id>, <link>, and <content>, which seem to be what
matter, so the {msgid} seems superfluous. Am I missing something?

--gh

[John Panzer]

This is purely to let clients re-try message creation safely -- if a reply from a previous PUT times out, it's always safe to re-attempt it without creating duplicate messages.  The message Id just a random string created by the client.
 

--gh

[Robert Evans]

Do we need to provide some hash generator library to provide non-colliding msg ids?