Re: [Messaging API] Feedback / Proposal

The reason for suggesting that the messages be broken up into type, receiver, and body (as well as other meta-data) is because I can see this API being used in ways where develops will be getting input from users, for instance:

	navigator.device.sendMessage("sms:" + phoneNumber + "?body=" + escape(body));

vs
	
	var msg = new navigator.device.messaging.SMS({
				           to: phoneNumber,
                                          body: body
	});
	msg.addEventListener("send", function() { alert("OK"); });
	msg.send();

Granted that the API could be a cross between the two suggestions:

	var msg = navigator.device.sendMessage({
					type: "sms",
				        to: phoneNumber,
                                       body: body
					success: function() { alert("OK"); },
					error: function() { alert("Error"); }
			   });

Which could be an interesting idea. My main dislike in the latest draft is that:
	a) It'll require some string concatenation to build up messages given user-input
	b) The string does kind of look a bit ugly and ungainly for developers to write, eg, the body must be escaped.
	c) It doesn't make use of the current fairly standard DOMEvents interface, which I think it should.

As to where the API actually lives, navigator.device.messaging or navigator.messaging, or which ever doesn't 
matter too much until the actual API to send the messages is solid.

Regards,
Micheil Smith
--
BrandedCode.com

On 21/04/2011, at 2:05 AM, Robin Berjon wrote:

> Hi Micheil,
> 
> thanks a lot for your feedback.
> 
> On Apr 19, 2011, at 11:36 , Micheil Smith wrote:
>> I saw the recently changed Device Messaging API draft [1], and couldn't help but feel that it 
>> seems extremely un-javascript-ish. I saw that the authors are looking for feedback on the 
>> API, so I composed an alternative API to the current one.
> 
> I certainly hear where you're coming from, but I would disagree that it's extremely un-javascript-ish. I've seen quite a few un-javascript-ish APIs over time, a lot of them very much Java-ish, and I don't think that this is one of them.
> 
> If you look at existing APIs, some of them are more string oriented while others decomposed things more. For instance, you have:
> 
>    var client = new XMLHttpRequest();
>    client.open("GET", "http://berjon.com/blog/2011/02/a-new-dap.html");
>    client.send();
> 
> where instead you could have:
> 
>    var client = new XMLHttpRequest();
>    client.open({
>                  method:  "GET",
>                  scheme:  "http",
>                  domain:  "berjon.com",
>                  path:    "/blog/2011/02/a-new-dap.html"
>    });
>    client.send();
> 
> It's not the only case, consider:
> 
>    elem.innerHTML = "<span class='creed'>Dahuts and Unicorns for the People</span>";
> 
> instead of:
> 
>    var span = document.createElement("span");
>    span.setAttribute("class", "creed");
>    span.textContent = ;
>    while (elem.firstChild) elem.removeChild(elem.firstChild);
>    elem.appendChild(span);
> 
> 
> So this isn't new territory, as we can see:
> 
>    navigator.sendMessage("mailto:robin@berjon.com?body=Welcome%20%to%Atlantis", null, function () { alert("OK"); }
> 
> (I'm pretending that we have a success callback as in the spec example but not the content, and that we've put the method directly on navigator rather than use the navigator.device indirection — it's the same change we've done elsewhere.)
> 
> Or your proposal:
> 
>    var msg = new navigator.messaging.Email({
>                                            to: "robin@berjon.com",
>                                            body: "Welcome to Atlantis"
>    });
>    msg.addEventListener("send", function() { alert("OK"); });
>    msg.send();
> 
> 
> My take on this is that neither design is bad — they just have different properties. I think that what matters is how well those properties map onto our goals and the ecosystem into which this API aims to integrate. The first thing I'll get out of the way is that your design is more verbose, but I don't think that that actually matters here — if it really turns out that it does a better job for our requirements, then verbosity isn't much of a factor.
> 
> At the heart of it, I think the differences boil down to goals. Your design seems to assume that the browser is handling the actual message sending whereas the idea behind the draft is just that it triggers a pre-filled message in the platform's mail|sms|mms|etc. agent which we feel is 1) better for security reasons, 2) easier to implement, and 3) more realistic in the short term. This shows in the following different properties.
> 
> • Multiple event types. Your design has open ended event types through addEventListener. One could for instance add progress events support (the primary use case I can see for this) to monitor the sending of the message as it goes down the pipe, and also differentiate between error and abort events. Where progress is concerned, it really requires the browser to do the sending, which is a bit of a problem for us. As for the error/abort difference, it could be captured on the error object (but see below). Given our goal of not requiring the browser to implement messaging internally, I don't see this as an advantage.
> 
>  • Multiple event listeners. I think that this mostly makes sense if the above works, e.g. a progress metre is notified of the progress of sending while a completely different component listens to success and error in order to show those to the user.
> 
>  • Fire-and-forget. You list this as a difference but actually both designs support this (you can set the callbacks to null). In fact, in the current draft you don't even have a success callback (I'm thinking that we should change that).
> 
>  • API surface. Our objective is essentially an upgrade to URI schemes, so a single method that does one thing and does it well works better than a more elaborate API IMHO.
> 
>  • Microsyntax. We use URI schemes as a microsyntax. There are many times when inventing a new syntax is bad, but in this case we're not inventing, we're reusing. Browsers already know how to parse these things and developers know how to write them. In general, I don't see this as a problem. It's easy to write a library to convert between both if needed.
> 
>  • Ability to abort send. This only works (AFAIK) if the browser is doing the sending itself. Otherwise, I don't think that platform messaging apps can get that information back.
> 
>  • Polling for state. Same as above.
> 
>  • Open ended URI schemes. With your design if a new message type is added (say a one-shot XMPP) then a new interface needs to be built and shipped. With the one in the draft, so long as the URI scheme is registered with the platform it can be communicated with (the actual details are more complicated, but the basic idea is there). I feel that that's a big strength that comes from using URIs.
> 
> So once we've eliminated what we would rather avoid having to support because we don't want to force implementers to have their own messaging stack, most of what's left is syntax, as it is URI vs JS object. All in all, I think that URIs have a slight edge there, and that the rest is largely about personal preferences and can be handled in a JS library.
> 
> What do you think?
> 
> -- 
> Robin Berjon - http://berjon.com/
> 
> 
>

Received on Wednesday, 20 April 2011 23:19:20 UTC