request* ResponseItem data

[Lou]

The 0.7 spec says that no data will be set on the ResponseItem for the
request* calls. Has there been any discussion on adding data to
successful responses? For example, our API servers will return the
following response for a call to send notifications:

{"notification_response":{"sent_ids":1000}}

If we standardized on some sort of similar response we could set the
ResponseItem data field and thereby notify developers which users
actually received their messages, which is something we've had
requests for and is a feature of the FB platform.

Is a standard response for activity and messages part of the REST API
proposal? And if so, is it stable enough for hi5 to implement that
response format for launch?

-Lou

[Lou]

hi5 would really like to pass some data back to developers in these
responses, indicating users to which the message was successfully
sent. Are there any thoughts on standardizing the format of this
response?

I'd propose setting data as:

requestSendMessage: Array<String> sent_ids
requestShareApp: Array<String> sent_ids
requestCreateActivity: String success (0 or 1)

feedback appreciated. we would like to do this for launch, and at
least don't want to be far off from what the spec might eventually
settle on.

[Kevin Brown]

I'd like to get this normalized within Shindig as well -- I don't like the idea of functions that attempt to do data modifications that don't provide a failure / success status.

--
~Kevin

[Evan Gilbert]

Couple of challenges:
- request* APIs usually have the contract that the container can navigate away from the current page and not call the callback. This is very useful for sites that have a more traditional (and less AJAX-y) page flow. I'm not sure how we would return responses in this case.
- I could see all of these APIs listed being handled on the server after the response is returned to the client (separate thread, batch process, etc). We could send a response back for whether it is OK from a permission standpoint, but not sure if we can provide a guarantee that messages have been sent to X people.

I agree with the problem statement, but don't have good solutions for the above issues. Can we get more detail on how the developers would like to use these features, and also brainstorm about what errors might occur beyond permissions?

[Lou]

Evan, you are definitely correct. For us, we have the response data to
pass back for requestSendMessage and requestCreateActivity, but we do
navigate away on requestShareApp and have no way to pass back the data
in that case.

one option for us is to provide another lifecycle event instead. We
have the optional hi5-lifecycle feature which allows developers to
specify callback urls for important lifecycle events which we ping
after server-side processing is done with some data. was hoping to
find something that was more inline with the current spec, but perhaps
the lifecycle feature is a good way to address it and should be folded
into opensocial.

Right now we support two events, install and remove:

<Optional feature="hi5-lifecycle">
<Param name="installPingUrl" value="http://yourserver/url"/>
<Param name="removePingUrl" value="http://yourserver/url"/>
</Optional>

if specified, we POST back to the given url with the userid of the
user taking the action. We could specify similar events for
postSharePingUrl, postMessagePingUrl, postActivityPingUrl that would
POST back the desired data, generally a list of userids to which the
request was successfully sent. They would probably need some way to
tie the ping back to the request that was sent, which could be
problematic (would senderid be enough? can get feedback from devs). if
we can work that out, this could potentially address both of the cases
you bring up, although we're open to other solutions as well.

-Lou

On Mar 25, 11:28 pm, Evan Gilbert <uid...@google.com> wrote:
> Couple of challenges:
> - request* APIs usually have the contract that the container can navigate
> away from the current page and not call the callback. This is very useful
> for sites that have a more traditional (and less AJAX-y) page flow. I'm not
> sure how we would return responses in this case.
> - I could see all of these APIs listed being handled on the server after the
> response is returned to the client (separate thread, batch process, etc). We
> could send a response back for whether it is OK from a permission
> standpoint, but not sure if we can provide a guarantee that messages have
> been sent to X people.
>
> I agree with the problem statement, but don't have good solutions for the
> above issues. Can we get more detail on how the developers would like to use
> these features, and also brainstorm about what errors might occur beyond
> permissions?
>

> On Tue, Mar 25, 2008 at 9:40 PM, Kevin Brown <e...@google.com> wrote:
> > I'd like to get this normalized within Shindig as well -- I don't like the
> > idea of functions that attempt to do data modifications that don't provide a
> > failure / success status.
>

[Maxwell Newbould]

Evan is correct, in the MySpace world, requestSendMessage will not
return a true message id due to the async nature of our backend. If a
response is required, it would at most be an acknowledgement that we
received a message, but not an actual message identifier.

If we chose to go the route of an optional callback with specific params
per container or use forced return values, most applications would have
to be doing a separate logic check.

I'm of the persuasion that we can support success/failure return values
at most while still maintaining true ambivalence towards containers.

Cheers,
Max

Max Newbould
Lead Developer/Product Owner
MySpace OpenSocial Container

[Lou]

i don't think not supporting meaningful return values for requests is
a viable option.

of course we would not want a feature that called for specific params
per container. although, frankly, if we start giving developers
valuable data of any kind many of them will take advantage of it even
if it means coding for each container. As we want to avoid that, we
should work towards a standard means of supporting it across
containers.

[Cassie]

Okay, I think we could perhaps change the spec to say this while making everybody happy:

 * @param {Function} opt_callback The function to call once the request has been
 *    processed; either this callback will be called or the gadget will be
 *    reloaded from scratch. This function will be passed one parameter, an
 *    opensocial.ResponseItem. The error code will be set to reflect whether
 *    there were any problems with the request. If there was no error, the
 *    message was sent. If there was an error, you can use the response item's
 *    getErrorCode method to determine how to proceed. The data on the response
 *    item may be set. If there was no error and the response item is not null, then
 *    it will be an array of person ids (Array<String>) indicating which people were
 *    successfully sent a message.
 *
 * @member opensocial
 */
opensocial.requestSendMessage = function(recipients, message, opt_callback) {


In 0.7, it says that the data will always be null. In 0.8 we can just say that the data will have <some return type> if it is set. So then myspace or others can choose to not return any data while other containers can standardize on something that is useful for developers. I think this will work for everyone, but please let me know if I've overlooked something.

If we do this, we just need to decide on the return types for each of the three functions of this form:

requestSendMessage
requestShareApp
requestCreateActivity

My idea was just to return an array of ids indicating who was sent a message, or who an app was shared with. This of course doesn't mean that someone actually read the message.. but just that it was delivered. I don't know what people want here, so please suggest some better response data.

Thanks!

- Cassie

[Evan Gilbert]

Possibly it makes sense to standardize the return value for
1. Permission exception cases - i.e., if the app or the user is not allowed to take this action. Not sure if this would be on a per-user-sent-to basis or just for the whole request.
2. Complete failure (i.e. "no donuts for you")

Otherwise I don't think we should be sending back responses - success with async operations will mean something different per container.

Are there other common failure modes that we would catch with a more robust return type?

Evan

[Cassie]

Well, the permission exception cases, the complete failure cases, and
any errors really are covered by the error field on the response item.
However, this is only going to give you a general error code.. it
won't tell you exactly who got the message and who didn't. For that
case to be covered we would either need to

1. Change the callback to take a Map<UserId, ResponseItem> so that you
would have one response item for each message attempted to be sent, or
2. Change the responseItem to have a defined return type which can be null.

You objected to #2, do you dislike #1 as well? Is there anything else
you can think of to handle this in a general way?
Thanks.

- Cassie

[Evan Gilbert]

Definitely works to have one response per user. Possibly more generally we could have responseItem.getErrors(), which can return 0-n errors with a given request (this is also useful for use cases such as form validation, where a user might have invalid values in multiple fields). This could also have arbitrary key / value maps along with each error.

Rough sample code:

var errors = responseItem.getErrors();
for (var i = 0; i < errors.length; i++) {
  var error = errors[i].
  if (error.getErrorCode() == opensocial.ResponseItem.Error.FORBIDDEN) {
   var userid = error.getParam('userid');
   handleMailNotSent(userid);
  }
}

Evan

[fer...@gmail.com]

So any further discussion here?

It seems like people at are odds on supporting fully javascript apis
(and containers), and/or giving containers more options such as
navigating away on calls like these.. but then that totally breaks the
whole idea of a full javascript api..

I say that we need to find a way to tell apps what actually happened
when they made these calls.. so options so far are:
1) DataResponse items
2) optional callback
3) asynch ping
4) app defined requestNavigateTo, after operation is complete.

I like the cleanliness of #1, but if we can't guarantee a fully
javascript dialog, etc.. then #4 is a requirement.

Here is my reasoning; user work flow and usability. Having your users
invite their friends is a key use case, and apps need to be able to
control what happens before and after that particular work flow. You
need to give the apps a chance to continue/follow through on whatever
workflow they were setting up; instead of always dumping users to the
app's home page..

That is why I asked for the requestShareApp to carry with it
NavigateTo parameters for where a user goes after they accept the
invite. I just realized that we also need NavigateTo parameters to
say where the inviting user goes after they send the invites.

Again, the fully javascript method is the cleaner (we can do logic
without having a full page refresh), but if that is not guaranteed, we
should be able to tell the container exactly what to do after their
page refreshes.

Further more, we should be able to ask the container (through features/
capabilities function), if they support full javascript callback, or
if they only support the full page refresh.. (then we can decide to
pass in the navigateTo parameters, or a callback function )...


Am I making any sense? Ideas? Questions?


1) to allow apps for clean control of use cases and unique user
workflows:
I propose to create a new object NavigateToParams; currently would
contain view and params.
I propose to change requestShareApp to allow it to take in an optional
NavigateToParams for "postInvite" and "postInviteAccept" and a
JavascripCallback for postInvite ( or i would prefer to do that
through normal DataResponse callbacks ).
I propose that these changes be considered for requestSendMessage and
any other method that might require the container to have to change
pages.

2) to allow easy way for apps to simply track invites sent and invites
accepted ( maybe for point rewards, etc )
I propose to add more ping urls for invites sent and invites
accepted. :)
( this is so apps can have different ways to track information,
without having to complicate the workflow and pages they have to
maintain ).

On Apr 14, 6:12 pm, Evan Gilbert <uid...@google.com> wrote:
> Definitely works to have one response per user. Possibly more generally we
> could have responseItem.getErrors(), which can return 0-n errors with a
> given request (this is also useful for use cases such as form validation,
> where a user might have invalid values in multiple fields). This could also
> have arbitrary key / value maps along with each error.
>
> Rough sample code:
> var errors = responseItem.getErrors();
> for (var i = 0; i < errors.length; i++) {
> var error = errors[i].
> if (error.getErrorCode() == opensocial.ResponseItem.Error.FORBIDDEN) {
> var userid = error.getParam('userid');
> handleMailNotSent(userid);
> }
>
> }
>
> Evan
>

[Evan Gilbert]

+1 on both of these proposals (NavigateToParams and more callbacks for invites)

[Evan Gilbert]

Bringing in Louis' comments from the other thread - he said that the app shouldn't always be able to set the view to navigate back to.

How many use cases are there where containers actually allow gadgets to navigate to any view besides canvas page? It doesn't really make sense for a gadget to navigate to a profile page, for example, because the gadget might not be on the profile page.

Possibly we can update this to take out the view parameter? Or alternately would be great if someone brought up the use cases where you should be able to set the view (I might just be missing something).

[fer...@gmail.com]

The NavigateToParams is just an container object that I imagined.. to
be able to encapsulate and talk about all the parameters together
( view, params, owner, etc ). But yes, it's a good idea to mention
default values (depending on where they are used). (like "canvas" for
view, {} for params, viewer as the owner). Or some containers could
always hard code to "canvas".. shrug.

But I feel these concerns are probably minor details and hope to not
derail the mail part of what I was talking about :) But you can read
on for my thoughts on the "view" parameter.



The question is can you prove that it will never be used?

At the moment there are "canvas" and "profile" as default views.
MySpace adds "home", Hi5 adds "preview", and aren't there another
proposal adding like 6 other views? Who is to say that another
container will not add variations to the canvas view ( wide-screen-
canvas, ad-supported-canvas, xxx-canvas, child-only-canvas, etc
etc )? Painting us into a corner via the API, it not necessarily in
the best of interest.

Or simply, let market forces and usability will be the ultimate judge,
if going to the profile view is beneficial, every will want it, if
it's not, everyone will laugh at you for trying. :) :)

I could also see how some containers would change their implementation
to allow/disallow some views that you can navigate to just because it
offends their sensibilities - much like they can for normal
requestNavigateTo method, yet we didn't take out the view parameter
there. But we should not assume every container will be - or needs to
be - so restrictive.

On Apr 22, 8:13 am, Evan Gilbert <uid...@google.com> wrote:
> Bringing in Louis' comments from the other thread - he said that the app
> shouldn't always be able to set the view to navigate back to.
>
> How many use cases are there where containers actually allow gadgets to
> navigate to any view besides canvas page? It doesn't really make sense for a
> gadget to navigate to a profile page, for example, because the gadget might
> not be on the profile page.
>
> Possibly we can update this to take out the view parameter? Or alternately
> would be great if someone brought up the use cases where you should be able
> to set the view (I might just be missing something).
>
> On Tue, Apr 22, 2008 at 8:08 AM, Evan Gilbert <uid...@google.com> wrote:
> > +1 on both of these proposals (NavigateToParams and more callbacks for
> > invites)
>

> > On Mon, Apr 21, 2008 at 9:43 AM, fern...@gmail.com <fern...@gmail.com>

> ...
>
> read more »

[Louis Ryan]

My objection has little to do with the diversity of views containers will support and more about user expectation.

The requestShareApp is a 'dialog' process, regardless of the user of interstitials or otherwise, as far as the user is concerned and redirecting users to a location other than the one they originated from once the dialog is completed is bad usability.

[Evan Gilbert]

Containers have the option to do a dialog or a page transition for requestShareApp(). We already handle. A callback param is already available for the dialog version. NavigateParams seems to be a good solution for the page transition version.

re: Views - let's just make the view another (optional) param in the params map instead of a separate param. I agree that it might be needed in the future, but the requestShareApp() use case above is a good example of not supporting choice of view.

[fer...@gmail.com]

Ah. Cool, your argument is stronger now. :)

But I still don't believe in forcing the hand of the apps. And the
requestShareApp does have two navigateTo params, one after the user
sends the invites, and one after a user accepts the invites. The one
where the user sends the invites is what you're talking about. The
one where the user accepts the invites is where you have to allow the
app to pick a view..

Either way, I don't see giving the app the choice as extremely
dangerous. If it turns out to be bad usability, apps will simply
leave that value as null and let the container pick the default view
( either canvas, or the current view they're one ). If some app comes
up with a great use case, then it kinda sucks that we limited their
ability and they have to complicate their logic to point to a page
just to redirect back to the view they really wanted to go to.

I propose to make sure we do keep the view parameter, but definitely
come up with good defaults, and give the apps just a little more lee-
way to pleasantly surprise us.

fernando

On Apr 23, 9:30 am, "Louis Ryan" <lr...@google.com> wrote:
> My objection has little to do with the diversity of views containers will
> support and more about user expectation.
>
> The requestShareApp is a 'dialog' process, regardless of the user of
> interstitials or otherwise, as far as the user is concerned and redirecting
> users to a location other than the one they originated from once the dialog
> is completed is bad usability.
>

> On Tue, Apr 22, 2008 at 2:38 PM, fern...@gmail.com <fern...@gmail.com>

[Louis Ryan]

+1 to Evan proposal to add it to opt_params

I just dont want to create false expectation here. Usability choices are made by both containers and gadgets in these scenarios and I have a hard time imagining many containers giving too much flexibility here.

[Paul]

requestNavigateTo can always be called from the callback function, so
I agree not adding the view as a specific parameter.

+1 to the idea of a generic data response for request*. I think an
array of ids would be fine, although maybe an array of Persons would
be appropriate as well. The latter fits the pattern of
requestFetchPerson and the dataResponse could essentially just to the
same thing to indicate the people in which the request* was
successful. I could see some apps wanting to display the users in
which the request* was successful (again just like
requestFetchPerson).

~Paul

[Cassie]

It seems that the request* threads have gotten very confused.
To be clear, this thread has nothing to do with views. It only has to do with defining return types on the response items returned asynchronously by various request* methods.
If you care about navigating to views and such this thread is what you want: http://groups.google.com/group/opensocial-and-gadgets-spec/browse_frm/thread/3f257fa792254f4c


To sum up the opinions related specifically to this issue:
- Lou, Kevin think that having the response item getData return the list of user ids for who messages were sent to is a good idea
- Evan and Max think that this isn't flexible enough and won't be able to work with all container types. Notably, myspace does this in an asynch way and won't be able to return a list of ids.

Goals:
- developers want to know who actually received a message, or an app invite.

Possible solutions:
1. we could add a lifecycle event type
2. we could define the return type on the responseItem.getData as originally proposed. containers that don't support this could just return null.
3. we could change the parameter passed into the requestSendMessage and requestShareApp methods to take in a Map<UserId, ResponseItem> so that containers could set errors for each recipient individually (ie user a = forbidden, user b = no error, user c = internal error).

Thoughts?
Thanks.

- Cassie

[Cassie]

Unfortunately, this thread does not seem to be getting enough feedback for 0.8. I would like to close this issue and continue the conversation for 0.9.
Thanks.

- Cassie