Yo Kai,
nice to hear from you again!
Love that http://browserplus.yahoo.com/developer/services/
Though I can only (seemingly) examine your JS APIs by clicking "Test". Which only works on the one machine I have with BP installed.
Is there some way I can see your IDLs for all your APIs in some overview HTML document?
So yes and no. As you'll see in the upcoming API docs, parameters and return values are programatically specified... to a point. For arguments to services the service developer must precisely specify the name and type of _top level_ arguments. The platform will then validate arguments very early in a call to ensure functions are correctly invoked. but it's only a single level, so map/list arguments to services there is no specification required and it's up to the service developer to provide documentation.
For return types and arguments to callbacks, there's no precise specification required.
During development at many times I've dreamed of a lightweight json schema language. There are several emergent projects/attempts to get this correct. The idea here would be that a schema language could be used to fully or partially specify the arguments to a service, the values it passes to callbacks, and its return value.
I've wanted to layer another library on top of yajl (http://github.com/lloyd/yajl/tree/master) and then look at using that in BrowserPlus. But alas, all of this is just thought experiments at the moment.
Your async APIs seem to use the (parameter, callback) pattern. Have you thought about migrating to something like the Geolocation pattern instead?
http://dev.w3.org/geo/api/spec-source.html
void getCurrentPosition(in PositionCallback successCallback, in PositionErrorCallback errorCallback, in PositionOptions options);
Which is kinda the reverse. Or is it too painful to do so?
because JavaScript is so flexible, I'd think it would be quite simple to create a tad of magic that would give you these semantics... a usage something like:
CallBPFunc('CurrentPosition.GetPosition')(in PositionCallback successCallback, in PositionErrorCallback errorCallback, in PositionOptions options)
And that could automatically map on top of
BrowserPlus.CurrentPosition.GetPosition(parameters, callback);
If you want to do this and share it, we've already got some stuff we'll be throwing in a playground on github with all sorts of frameworks and tools targeted at both javascript authors and service developers. The thought is let's try on a lot of different ideas and figure out what works best and what people like the most.
At a high level, we really need this type of exploration. How should a service API look? How much control should the service author have over how it's expressed into javascript? What interaction patterns are missing?
In some eventual future when we've got enough usage of browserplus and thought in this area we could roll all the best ideas into BrowserPlus 3 which improves the current API.
sorry for the verbosity.. I may be over-caffeinated.
lloyd
