[0.9 Updated Proposal] Lightweight JS APIs

[Evan Gilbert]

We came to agreement at the 0.9 summit on almost all issues - updated proposal has been posted:
http://wiki.opensocial.org/index.php?title=Lightweight_JS_APIs

There were a number of ideas about the "right" method signature for the data calls, so I created a section on the Wiki for people to post proposals. If you'd like to submit an option for the method signature, please review the requirements we are aiming for, and include a spec as well as sample code for:

• Getting just the viewer's name and birthday
• Request group that gets viewer, viewer friends (both with birthdays), and makes a request to a 3rd party site
• Update request that sets one app data value

I'm hoping that we can separate the discussion on the exact syntax for the APIs from a general voting on this proposal.

Change Log
11/18/08 - Updated with feedback from OpenSocial 0.9 summit:

• Officially proposed new namespace: "osapi"
• Officially proposed request* APIs being moved to new namespace
• Moved "request group" syntax to a separate section where alternate proposals can easily be compared side by side

Evan

[Scott Seely]

Lightweight JS APIs needs a few tweaks to be acceptable:

1.       Osapi.activities needs to incorporate the already accepted paging proposal (http://wiki.opensocial.org/index.php?title=Activity_Paging)

2.       Osapi.people: Needs to incorporate anonymous user information: http://wiki.opensocial.org/index.php?title=Anonymous_Viewer

3.       Callback execution is not explicit. http://wiki.opensocial.org/index.php?title=Clarify_timing_of_callback_execution_in_JS_API

4.       Osapi.ui.shareApp needs to take an idspec, not a comma delimited list of userIDs. (http://wiki.opensocial.org/index.php?title=RequestShareApp_and_requestSendMessage_should_use_IdSpec)

5.       Osapi.ui.messages.send() needs to handle the IdSpec issue too.

 

I’m concerned that the lack of an actual JS as used for the rest of the API is hurting our ability to feel comfortable voting on this. We agree on the principle, but this is an API simplification and so, the details are important.

[Adam Winer]

I'd also like to see an explicit specification of the semantics of execution order within a "batch".

Preference: 

 - The results of batch execution MUST be indistinguishable from executing each element within the batch serially.  Consequently, errors within the batch do not result in early termination of the batch.

The "UI" elements complicate this greatly, and I'd be inclined to remove those from batching.

FWIW, I added an Option B to the syntax.

On Fri, Nov 21, 2008 at 8:03 AM, Scott Seely <sSe...@myspace.com> wrote:

Lightweight JS APIs needs a few tweaks to be acceptable:

1.       Osapi.activities needs to incorporate the already accepted paging proposal (http://wiki.opensocial.org/index.php?title=Activity_Paging)

2.       Osapi.people: Needs to incorporate anonymous user information: http://wiki.opensocial.org/index.php?title=Anonymous_Viewer

3.       Callback execution is not explicit. http://wiki.opensocial.org/index.php?title=Clarify_timing_of_callback_execution_in_JS_API

4.       Osapi.ui.shareApp needs to take an idspec, not a comma delimited list of userIDs. (http://wiki.opensocial.org/index.php?title=RequestShareApp_and_requestSendMessage_should_use_IdSpec)

I disagree - they should take @userIds and @groupId, as that's what an endpoint would do.

5.       Osapi.ui.messages.send() needs to handle the IdSpec issue too.

Ditto. 

[Scott Seely]

Adam—While you may disagree, you never disagreed when the topic came up in discussion. Please see http://groups.google.com/group/opensocial-and-gadgets-spec/browse_thread/thread/48dfeaa000f470c3/ for the idSpec issues. The proposal was accepted and has not seen a -1. You can go to the thread and vote a -1 per our process. If you choose to do so, it would be good of you to also follow up with a mechanism to fix things so that security is handled the same way across OpenSocial instead of allowing the current one-off situation to exist for two methods.

 

I look forward to your feedback.

[Adam Winer]

On Fri, Nov 21, 2008 at 12:37 PM, Scott Seely <sSe...@myspace.com> wrote:

Adam—While you may disagree, you never disagreed when the topic came up in discussion. Please see http://groups.google.com/group/opensocial-and-gadgets-spec/browse_thread/thread/48dfeaa000f470c3/ for the idSpec issues. The proposal was accepted and has not seen a -1. You can go to the thread and vote a -1 per our process. If you choose to do so, it would be good of you to also follow up with a mechanism to fix things so that security is handled the same way across OpenSocial instead of allowing the current one-off situation to exist for two methods.

You're missing my point.  I agree with that thread, and that the old requestSendMessage() should take IdSpec objects  My point is that the *new* lightweight JS APIs should have @userId and @groupId attributes.  Those aren't incompatible.

-- Adam

[Scott Seely]

I’m more interested in having security be consistent than in being an IDSpec. Whichever works best for the API.

[Adam Winer]

I think we agree:

  - the old API should use IdSpec (the thread you refer to)

  - the new API should use userId, groupId

Do we agree on this?

[Evan Gilbert]

For a few items, the Lightweight JS API just refers to the REST/RPC spec - only functions with no REST equivalent are specified in this proposal.

On Fri, Nov 21, 2008 at 8:03 AM, Scott Seely <sSe...@myspace.com> wrote:

Lightweight JS APIs needs a few tweaks to be acceptable:

1.       Osapi.activities needs to incorporate the already accepted paging proposal (http://wiki.opensocial.org/index.php?title=Activity_Paging)

Refers to REST/RPC spec

2.       Osapi.people: Needs to incorporate anonymous user information: http://wiki.opensocial.org/index.php?title=Anonymous_Viewer

Refers to REST/RPC spec

3.       Callback execution is not explicit. http://wiki.opensocial.org/index.php?title=Clarify_timing_of_callback_execution_in_JS_API

Covered in http://wiki.opensocial.org/index.php?title=Lightweight_JS_APIs#Requirements (and matches the other proposal)

4.       Osapi.ui.shareApp needs to take an idspec, not a comma delimited list of userIDs. (http://wiki.opensocial.org/index.php?title=RequestShareApp_and_requestSendMessage_should_use_IdSpec)

Updated

5.       Osapi.ui.messages.send() needs to handle the IdSpec issue too.

Refers to REST/RPC spec, but the RPC spec should probably be updated to clarify that recipients can also be groups.

 

I'm concerned that the lack of an actual JS as used for the rest of the API is hurting our ability to feel comfortable voting on this. We agree on the principle, but this is an API simplification and so, the details are important.

I'm hoping to avoid putting too many details in this spec :)

In all seriousness, that is a goal - it should just refer to the existing API specifications for REST.  Can you clarify what details might help? 

[Evan Gilbert]

On Fri, Nov 21, 2008 at 12:03 PM, Adam Winer <awi...@gmail.com> wrote:

I'd also like to see an explicit specification of the semantics of execution order within a "batch".

Preference: 

 - The results of batch execution MUST be indistinguishable from executing each element within the batch serially.  Consequently, errors within the batch do not result in early termination of the batch.

Added to Requirements (note the more neutral "request group" terminology):

• All items in a request group will be executed - errors within one item in the request group do not affect processing of other items
  • Only exception is ff there is a UI action in the request group that results in the user navigating away from the page, then none of the items in the request group will be executed. More details in osapi.ui.* section.
  • The container must execute all items in a request group must serially or in a manner that is indistinguishable to serial execution

 

[Evan Gilbert]

On Fri, Nov 21, 2008 at 3:02 PM, Adam Winer <awi...@gmail.com> wrote:

I think we agree:

  - the old API should use IdSpec (the thread you refer to)

  - the new API should use userId, groupId

Do we agree on this?

I found the source of confusion when reading through the details of both propsals. There are two types of groups now in the spec:
1. Groups relative to a user. In this case we would use @groupId
2. Objective groups. In that case we pass in @recipients, which can be a list of user IDs or group IDs.

For both sendMessage, and shareApp, the proposal is to support #2, so @recipients with a list of entity IDs is in the proposal now (for shareApp(), sendMessage just refers to the REST spec).

Evan

[Evan Gilbert]

It seems as if people are generally supportive of this proposal - are there other details to work out or other concerns?

If so, please bring up on the thread. If not... +1s are welcome.

Evan

P.S. Sorry for the repeated emails - I wanted to respond inline to the previous comments.

[Louis Ryan]

I think the timing requirements make it difficult to include requestXXX calls in data batches and would require some fairly complex coordination of events between XHR calls and cross-iframe rpcs. Im not sure they need to be batchable with data fetches either from a functional standpoint so Id rather just have them take standard callbacks instead.

From a nomenclature standpoint I prefer having requestCreateXXX methods live on the typed service as opposed to some osapi.ui namespace. That is

osapi.activities.requestCreate 

osapi.messages.requestCreate

non-data centric methods can still happily live on osapi.ui like shareApp, requestPermission

[Scott Seely]

yup

[Evan Gilbert]

Good feedback Louis...

Made the following changes reflecting these suggestions:
- osapi.ui.messages.send() -> osapi.messages.requestSend()
- osapi.ui.activity.create() -> osapi.activities.requestCreate()
- Request* APIs aren't batchable. Details for request*() semantics are now in a separate top level section

On Fri, Nov 21, 2008 at 6:06 PM, Louis Ryan <lr...@google.com> wrote:

I think the timing requirements make it difficult to include requestXXX calls in data batches and would require some fairly complex coordination of events between XHR calls and cross-iframe rpcs. Im not sure they need to be batchable with data fetches either from a functional standpoint so Id rather just have them take standard callbacks instead.

For many use cases, the request* calls will function identically to raw data APIs - i.e. app has permission to create an activity, and the call just succeeds.

However, they do have 2 key differences:
1. They may create UI, and
2. They can fill in parameters for the developer (i.e. possibly user can set recipients or modify message)

So I'm thinking that your suggestion is right, that they shouldn't be batchable. We can create equivalent data APIs that are batchable and only succeed or fail if there is demand.
 

From a nomenclature standpoint I prefer having requestCreateXXX methods live on the typed service as opposed to some osapi.ui namespace. That is

osapi.activities.requestCreate 

osapi.messages.requestCreate

Yep, this is nicer.
 

[Evan Gilbert]

I think I've resolved issues regarding userId/groupId - Scott / Adam please respond back if there are more updates needed.

Evan

[Scott Seely]

With user/group IDs, we would then use the proposal made in section 10 of messaging (http://sites.google.com/site/opensocialdraft/Home/restful-protocol-specification#TOC-Semantics)? By default, the identifier is a person unless the type specifier is present?

 

If so I think things are logically coherent then, so +1

[Louis Ryan]

Scott,

I dont think theres any conflict here. The JSON encoding would be

osapi.messages.put({...., recipients : [ "example.org:12345", "example.org:group:12345"] ..}, ...)

Im +1 now. Should we start a separate vote on which of the syntax variants we prefer?

-Louis

[Evan Gilbert]

(and again, I'm +1 - just want to make sure the proposer's vote is counted :)

[Scott Seely]

I never said there was a conflict. I just want to make sure I understand what the idspec equivalent is and needed a yes|no answer to what we’d see. I don’t want a separate vote—we already said that the naming pattern was fine for messages. Let’s just roll that decision in here (as always—speak up if anyone disagrees).

 

Consistency on this is important to me.

[Lane LiaBraaten]

+1 - can't wait to start using this new API!

On 11/24/08, Scott Seely <sSe...@myspace.com> wrote:
> I never said there was a conflict. I just want to make sure I understand
> what the idspec equivalent is and needed a yes|no answer to what we'd

> see. I don't want a separate vote-we already said that the naming

> pattern was fine for messages. Let's just roll that decision in here (as

> always-speak up if anyone disagrees).

> Adam-While you may disagree, you never disagreed when the topic came up

> <http://wiki.opensocial.org/index.php?title=Lightweight_JS_APIs#Requirem
> ents> we are aiming for, and include a spec as well as sample code for:
>
>
> * Getting just the viewer's name and birthday
> * Request group that gets viewer, viewer friends

> (both with birthdays), and makes a request to a 3rd party site

> * Update request that sets one app data value

>
> I'm hoping that we can separate the discussion on the
> exact syntax for the APIs from a general voting on this proposal.
>
> Change Log

> <http://wiki.opensocial.org/index.php?title=Lightweight_JS_APIs#Change_L
> og>

> 11/18/08 - Updated with feedback from OpenSocial 0.9
> summit:
>

> * Officially proposed new namespace: "osapi"
> * Officially proposed request* APIs being moved to
> new namespace
> * Moved "request group" syntax to a separate

> section where alternate proposals can easily be compared side by side
>
> Evan
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
> >
>

--
Sent from my mobile device

[Chris Chabot]

+1 and indeed, can't wait to use it :)

[Scott Seely]

I think we are at +5 here:

 

Chris Chabot, Lane LiaBraaten, Louis Ryan, Me, Evan Gilbert

 

Any detractors?