Refactor API signatures

[djensen47]

Currently the API works on this signature pattern:

vehicle.dataPoint.method

But dataPoint is, in a sense, just data, i.e, meta-data, itself.

Since we are dealing with many dozen data points some of which may or may not be implemented, something the following this seems cleaner.

vehicle.method(dataPoint, params…)

Now it doesn't appear as if there are dozens or hundreds of APIs, now we have 3 or 4. It also leaves some flexibility to the implementation. Maybe, it's not a 1-to-1 mapping to the clib implementation but I don't think it should be. This is JavaScript/ECMAScript not C.

• vehicle.get(data, options)
• vehicle.set(data, value, options)
• vehicle.subscribe(data, options, callback)
• vehicle.unsubscribe(data, handler)
• vehicle.availableFor...(data)

data is simply a String, the name of the data point like 'vehicleSpeed'
options include information like zone, event period

This also avoids the issue where vehicle.vehicleSpeed.get() could result in a Cannot call method 'get' of undefined if vehicleSpeed is not implemented.

[tripzero]

On Jun 1, 2015 1:10 PM, "Dave Jensen" notifications@github.com wrote:

Currently the API works on this signature pattern:

vehicle.dataPoint.method

But dataPoint is, in a sense, just data, i.e, meta-data, itself.

It can more correctly be thought of as vehicle.dataInterface.method.

Since we are dealing with many dozen data points some of which may or may
not be implemented, something the following this seems cleaner.

vehicle.method(dataPoint, params…)

Now it doesn't appear as if there are dozens or hundreds of APIs, now we
have 3 or 4. It also leaves some flexibility to the implementation. Maybe,
it's not a 1-to-1 mapping to the clib implementation but I don't think it
should be. This is JavaScript/ECMAScript not C.

vehicle.get(data, options)
vehicle.set(data, value, options)
vehicle.subscribe(data, options)
vehicle.unsubscribe(data)
vehicle.availableFor...(data)

data is simply a String, the name of the data point like 'vehicleSpeed'

Members were concretely defined to avoid magic strings.

options include information like zone, event period

This also avoids the issue where vehicle.vehicleSpeed.get() could result
in a Cannot call method 'get' of undefined if vehicleSpeed is not
implemented.

This is a feature, not a bug. The idea was to take advantage of
JavaScript's introspection capabilities as one more means of understanding
what data is available.

—
Reply to this email directly or view it on GitHub.

[tripzero]

One other reason to keep it like it is is that development becomes easier
when instead of having to remember several hundred magic strings, you let
your editor help if it has autocomplete/introspection capabilities.
On Jun 1, 2015 5:15 PM, "Kevron Rees" tripzero.kev@gmail.com wrote:

On Jun 1, 2015 1:10 PM, "Dave Jensen" notifications@github.com wrote:

Currently the API works on this signature pattern:

vehicle.dataPoint.method

But dataPoint is, in a sense, just data, i.e, meta-data, itself.

It can more correctly be thought of as vehicle.dataInterface.method.

Since we are dealing with many dozen data points some of which may or
may not be implemented, something the following this seems cleaner.

vehicle.method(dataPoint, params…)

Now it doesn't appear as if there are dozens or hundreds of APIs, now we
have 3 or 4. It also leaves some flexibility to the implementation. Maybe,
it's not a 1-to-1 mapping to the clib implementation but I don't think it
should be. This is JavaScript/ECMAScript not C.

vehicle.get(data, options)
vehicle.set(data, value, options)
vehicle.subscribe(data, options)
vehicle.unsubscribe(data)
vehicle.availableFor...(data)

data is simply a String, the name of the data point like 'vehicleSpeed'

Members were concretely defined to avoid magic strings.

options include information like zone, event period

This also avoids the issue where vehicle.vehicleSpeed.get() could result
in a Cannot call method 'get' of undefined if vehicleSpeed is not
implemented.

This is a feature, not a bug. The idea was to take advantage of
JavaScript's introspection capabilities as one more means of understanding
what data is available.

—
Reply to this email directly or view it on GitHub.

[djensen47]

This is a feature, not a bug. The idea was to take advantage of
JavaScript's introspection capabilities as one more means of understanding
what data is available.

But now all of your code must check both the availability api, check for null, and handle an error in the callback.

[djensen47]

Members were concretely defined to avoid magic strings.

Is it "magic" if it is defined in documentation and specification?

[tripzero]

On Jun 1, 2015 5:32 PM, "Dave Jensen" notifications@github.com wrote:

This is a feature, not a bug. The idea was to take advantage of
JavaScript's introspection capabilities as one more means of
understanding
what data is available.

But now all of your code must check both the availability api, check for
null, and handle an error in the callback.

Initially, we had all attributes on vehicle as non-nullable. I don't know
if that has changed but if not, the null check is not necessary.

—
Reply to this email directly or view it on GitHub.

[wonsuk73]

@djensen47 Thanks for raising this issue. I fully agree with making unified APIs for accessing vehicle information than separate APIs. I think we could have the benefits like

• Flexibility: I think vehicle information web app developer would like to access might be expanded. so it's important whether it's well designed for flexibility or not.
• Consistency: For web app developer, it would be great if we could provide consistent APIs for them. Might be web app developer can use these APIs more easily if it has consistent pattern.
• Maintenance: In the aspect of platform developer (e.g. Tizen, Firefox OS, brower vendors), they don't want to make many APIs because it makes more efforts to maintain those APIs.
• Referring other WGs: Device APIs WG [1] is trying to make Sensor APIs like Proximity, Ambient Light and extra. They has made Candidate REC for them at Oct. 2013, but WG changes the direction of their API design approach from separate APIs to Unified style API [2]. So CR specs was pending so far. the other case is Metadata API for Media Resources 1.0 [3], which defines an API to access metadata information related to media resources on the Web. The overall purpose is to provide developers with a convenient access to metadata information stored in different metadata formats.

[1] http://www.w3.org/2009/dap/
[2] https://github.com/wonsuk73/sensors
[3] http://www.w3.org/TR/mediaont-api-1.0

[tripzero]

On Jun 2, 2015 8:57 AM, "Wonsuk Lee" notifications@github.com wrote:

@djensen47 Thanks for raising this issue. I fully agree with making
unified APIs for accessing vehicle information than separate APIs. I think
we could have the benefits like

1. Flexibility: I think vehicle information web app developer would like
   to access might be expanded. so it's important whether it's well designed
   for flexibility or not.

2. Consistency: For web app developer, it would be great if we could
   provide consistent APIs for them. Might be web app developer can use these
   APIs more easily if it has consistent pattern.

The current API is internally consistent. The pattern is basic object
oriented design: object.method(). This is probably well known. The
proposal is turn it into method("stringKey"). That said, this is
javascript and javascript is magic: you can use strings without any API
changes if you really want to:

vehicle["vehicleSpeed"].get()

it's basically the same as vehicle.get("vehicleSpeed") ;).

3. Maintenance: In the aspect of platform developer (e.g. Tizen, Firefox
   OS, brower vendors), they don't want to make many APIs because it makes
   more efforts to maintain those APIs.

I don't think removing the object-orientedness helps here. I may still
have the only implementation in Automotive Message Broker of the API.
Using strings doesn't save me any coding as far as I can imagine.

4. Referring other WGs: Device APIs WG [1] is trying to make Sensor APIs
   like Proximity, Ambient Light and extra. They has made Candidate REC for
   them at Oct. 2013, but WG changes the direction of their API design
   approach from separate APIs to Unified style API [2]. So CR specs was
   pending so far. the other case is Metadata API for Media Resources 1.0 [3],
   which defines an API to access metadata information related to media
   resources on the Web. The overall purpose is to provide developers with a
   convenient access to metadata information stored in different metadata
   formats.

[1] http://www.w3.org/2009/dap/
[2] https://github.com/wonsuk73/sensors
[3] http://www.w3.org/TR/mediaont-api-1.0

[tripzero]

wow, that reply got butchered... fixed

[eorroe]

I have the following

Proposal

How about better property and method naming:

Why have vehicle.vehicleSpeed? Why not vehicle.speed?

At first I had the thought of using a getter for getting the vehicle's speed:

vehicle.speed would just return a promise.

No need for a get() method if the get() method is still a synchronous call (just like a getter) to return a Promise which will then allow the following:

var vehicle = navigator.vehicle;
vehicle.speed.then(speed => console.log(speed));

But why does it need to be a Promise not every part of the api has to be Promise based.

It's not like it's requesting something that's remote. It should be optimized to read the car speed to be synchronous no? (I could be wrong)

Therefore this should be possible:

vehicle.speed; // returns the vehicle's speed.

Now the only other way to set the Speed of the car would easily be:

vehicle.speed = (new speed) // sets the new speed

Now if you guys want to be method based:

vehicle.getSpeed(); // returns vehicle's speed

vehicle.setSpeed( (new speed) ); // sets the new speed and returns a promise simply because the vehicle will take time to get to the new speed.

This is what I meant by better naming

I also saw speed histories:

vehicle.speedHistory; // returns the same object history that's being used now

The vehicle's Doors:

vehicle.lockDoor(zone.driver); // locks door

Why pass an object {"lock" : true} to vehicle.door.lock() when we could just have vehicle.lockDoor()

Is there anything else to pass to that object perhaps an open attribute? (For cars doors that open and close automatically)

vehicle.door.set({lock: true, open: true}, zone.driver).then(resolve, reject);

Could be turned to:

vehicle.lockDoor(zone.driver); // returns a promise
vehicle.openDoor(zone.driver); // returns a promise

Like you guys mentioned about people having to remember the strings, same thing with an object which is even more complicated than a simple string

Again it's all about good method naming. IMHO It's easier and better.

This is what I see with the current api:

{
  vehicleSpeed: {
    get() {}, // returns promise
    set() {} // returns promise
  },
  door: {
    get() {}, // returns promise
    set() {} // returns promise
  }
}

Now my proposal would be:

{
  getSpeed() {} // returns car's speed
  setSpeed(newSpeed) {}, // returns a promise with the new speed
  lockDoor() {}, // returns a promise
  unlockDoor() {}, // returns a promise
  openDoor() {}, // returns a promise
  closeDoor() {} // returns a promise
}

In the above all do what the method name says, and takes a callback.

Or it could sort of stay the same and be:

{
 speed: {
  get() {}, // returns car's speed
  set(newSpeed) {}, // returns a promise with the new speed
 },

 door: {
  lock() {}, // returns a promise
  unlock() {}, // returns a promise
  open() {}, // returns a promise
  close() {} // returns a promise
 }
}

Conclusion

I understand that you guys are with the vehicle.dataInterface.method way of doing this but there's really no need. It'll be less code for developers and for the API. However if were sticking to that, let's at least still use the good method naming (The Last One)

Also my proposal get's rid of passing objects that can be taken cared of with Good Method Naming. No need for get() and set() methods everywhere. Believe me it'll be much easier than having to check the properties of the passed object.

[tripzero]

But what about subscribe?
On Jun 20, 2015 12:00 AM, "Edwin Reynoso" notifications@github.com wrote:

I have the following
Proposal

How about better property and method naming:

Why have vehicle.vehicleSpeed? Why not vehicle.speed?

At first I had the thought of using a getter for getting the vehicle's
speed:

vehicle.speed would just return a promise.

No need for a get() method if the get() method is still a synchronous
call (just like a getter) to return a Promise which will then allow the
following:

var vehicle = navigator.vehicle;
vehicle.speed.then(speed => console.log(speed));

But why does it need to be a Promise not every part of the api has to be
Promise based.

It's not like it's requesting something that's remote. It should be
optimized to read the car speed to be synchronous no? (I could be wrong)

Therefore this should be possible:

vehicle.speed; // returns the vehicle's speed.

Now the only other way to set the Speed of the car would easily be:

vehicle.speed = (new speed) // sets the new speed

Now if you guys want to be method based:

vehicle.getSpeed(); // returns vehicle's speed

vehicle.setSpeed( (new speed) ); // sets the new speed and returns a promise simply because the vehicle will take time to get to the new speed.

This is what I meant by better naming

I also saw speed histories:

vehicle.speedHistory; // returns the same object history that's being used now

The vehicle's Doors:

vehicle.lockDoor(zone.driver); // locks door

Why pass an object {"lock" : true} to vehicle.door.lock() when we could
just have vehicle.lockDoor()

Is there anything else to pass to that object perhaps an open attribute?
(For cars doors that open and close automatically)

vehicle.door.set({lock: true, open: true}, zone.driver).then(resolve, reject);

Could be turned to:

vehicle.lockDoor(zone.driver); // returns a promise
vehicle.openDoor(zone.driver); // returns a promise

Like you guys mentioned about people having to remember the strings, same
thing with an object which is even more complicated than a simple string

Again it's all about good method naming. IMHO It's easier and better.

This is what I see with the current api:

{
vehicleSpeed: {
get() {}, // returns promise
set() {} // returns promise
},
door: {
get() {}, // returns promise
set() {} // returns promise
}
}

Now my proposal would be:

{
getSpeed() {} // returns car's speed
setSpeed(newSpeed) {}, // returns a promise with the new speed
lockDoor() {}, // returns a promise
unlockDoor() {}, // returns a promise
openDoor() {}, // returns a promise
closeDoor() {} // returns a promise
}

In the above all do what the method name says, and takes a callback.

Or it could sort of stay the same and be:

{
speed: {
get() {}, // returns car's speed
set(newSpeed) {}, // returns a promise with the new speed
},

door: {
lock() {}, // returns a promise
unlock() {}, // returns a promise
open() {}, // returns a promise
close() {} // returns a promise
}
}

Conclusion

I understand that you guys are with the vehicle.dataInterface.method way
of doing this but there's really no need. It'll be less code for developers
and for the API. However if were sticking to that, let's at least still use
the good method naming (The Last One)

Also my proposal get's rid of passing objects that can be taken cared of
with Good Method Naming. No need for get() and set() methods
everywhere. Believe me it'll be much easier than having to check the
properties of the passed object.

—
Reply to this email directly or view it on GitHub
#37 (comment).

[eorroe]

I only mentioned certain parts everything else that will be implemented will follow the pattern you guys decide on choosing. Since you guys want the vehicle.dataInterface.method I'd suggest the last option.

[djensen47]

vehicle["vehicleSpeed"].get()

it's basically the same as vehicle.get("vehicleSpeed") ;).

I disagree.

In the first one, vehicleSpeed is a property of vehicle, that property happens to be an object with a method get. It requires vehicleSpeed to be a property.

In the second one, get is a function on vehicle, get takes vehicleSpeed as a parameter.

When you invoke vehicle.vehicleSpeed.get() the vehicleSpeed property must already exist, it needs to have been initialized. Not only that, all properties will bee to be initialized, even the properties that will never be used by the developer.

But vehicle.get() doesn't force the implementor to initialize everything on vehicle object. They can dynamically initialize at runtime if need be.

I don't think removing the object-orientedness helps here. I may still
have the only implementation in Automotive Message Broker of the API.
Using strings doesn't save me any coding as far as I can imagine.

It depends on whether you consider vehicleSpeed a property or an object. I was taking the perspective that it is a property and not an object.

Using the vehicle.get() does help with code readability and maintenance. It does not require a null check before you invoke get on vehicle speed.

if (vehicle.vehicleSpeed) {
  vehicle.vehicleSpeed.get().then(
    function(result) {
      //do some work
    },
    function(error) {
      //handle error
    });
}

The following seems like cleaner code to me:

vehicle.vehicleSpeed.get("vehicleSpeed").then(
  function(result) {
    //do some work
  },
  function(error) {
    //handle error, including "attribute does not exist"
});

As an aside, let's remind ourselves that JavaScript isn't a pure object-oriented language it's also functional and dynamic, i.e., it's not Java and shouldn't be treated like Java.

I'm starting to wonder if both ideas are not quite right. I don't completely agree that they are the same but, yes, in a sense they are similar.

Since promises are just a stop-gap before we have generators, I wonder if it would be a good exercise to consider what the API would look like if we were in an ES6 world and had generators.

[eorroe]

Wait @djensen47 I'm confused, I'm not sure if you replied to anything I said. Was any of that towards what I said or to @tripzero If it was towards him, what do you think about what I mentioned?

[djensen47]

I was responding to @tripzero. I haven't gone through your post yet.
On Jun 21, 2015 2:59 PM, "Edwin Reynoso" notifications@github.com wrote:

Wait @djensen47 https://github.com/djensen47 I'm confused, I'm not sure
if you replied to anything I said. Was any of that towards what I said or
to @tripzero https://github.com/tripzero If it was towards him, what do
you think about what I mentioned?

—
Reply to this email directly or view it on GitHub
#37 (comment).

[tripzero]

On Sat, Jun 20, 2015 at 10:14 PM, Dave Jensen notifications@github.com
wrote:

vehicle["vehicleSpeed"].get()

it's basically the same as vehicle.get("vehicleSpeed") ;).

I disagree.

In the first one, vehicleSpeed is a property of vehicle, that property
happens to be an object with a method get. It requires vehicleSpeed to
be a property.

This is a distinction without a functional difference. If you don't
initialize the property you get an error. If you don't support the
"string", you get an error.

In the second one, get is a function on vehicle, get takes vehicleSpeed
as a parameter.

When you invoke vehicle.vehicleSpeed.get() the vehicleSpeed property must
already exist, it needs to have been initialized. Not only that, all
properties will bee to be initialized, even the properties that will never
be used by the developer.

Is this a performance argument?

But vehicle.get() doesn't force the implementor to initialize everything
on vehicle object. They can dynamically initialize at runtime if need be.

You can initialize properties programitically:
https://github.com/otcshare/automotive-message-broker/blob/master/xwalk/vehicle_api.js#L307

This bit of code generates properties that are supported by the backend.

I don't think removing the object-orientedness helps here. I may still
have the only implementation in Automotive Message Broker of the API.
Using strings doesn't save me any coding as far as I can imagine.

It depends on whether you consider vehicleSpeed a property or an object. I
was taking the perspective that it is a property and not an object.

Using the vehicle.get() does help with code readability and maintenance.
It does not require a null check before you invoke get on vehicle speed.

This is not correct. All attributes on vehicle are mandatory. No null
check is necessary (see
https://rawgit.com/w3c/automotive-bg/master/data_spec.html#runningstatus-interfaces
attributes are not nullable types).

if (vehicle.vehicleSpeed) {
vehicle.vehicleSpeed.get().then(
function(result) {
//do some work
},
function(error) {
//handle error
});
}

The following seems like cleaner code to me:

vehicle.vehicleSpeed.get("vehicleSpeed").then(
function(result) {
//do some work
},
function(error) {
//handle error, including "attribute does not exist"
});

As an aside, let's remind ourselves that JavaScript isn't a pure
object-oriented language it's also functional and dynamic, i.e., it's not
Java and shouldn't be treated like Java.

I'm starting to wonder if both ideas are not quite right. I don't
completely agree that they are the same but, yes, in a sense they are
similar.

They are two different ways of doing the same thing. It's really a style
issue but there are advantages in having properties: code complete
features, introspection, established object oriented pattern. Since
javascript is dynamic, you can add a line to make your life as a developer
easier if you really like the "vehicle.get()" approach:

vehicle.get = function(propName) { return vehicle[propName].get(); }

Since promises are just a stop-gap before we have generators, I wonder if
it would be a good exercise to consider what the API would look like if we
were in an ES6 world and had generators.

This is a good point and should be investigated further.

—
Reply to this email directly or view it on GitHub
#37 (comment).

[djensen47]

But vehicle.get() doesn't force the implementor to initialize everything
on vehicle object. They can dynamically initialize at runtime if need be.

You can initialize properties programitically:
https://github.com/otcshare/automotive-message-broker/blob/master/xwalk/vehicle_api.js#L307

This bit of code generates properties that are supported by the backend.

Let's say vehicle.vehicleSpeed has not been initialized. Typically vehicle.vechicleSpeed will be undefined. Prior to ES6 Proxies properties have to be initialized/defined before they are used. In your code, yes you're dynamically creating the properties but you have to initialize all of them at once. With vehicle.get('vehicleSpeed') the property or object that represents vehicleSpeed need not exist prior to being used. The implementation can dynamically construct that object at runtime as needed.

//implement vehicle.get()
var vehicle = (function() {
  var v = {}; 
  v.get = function vehicleGet(property) {
    if (!v[property]) {
      //init is defined elsewhere, it creates the object
      v[property] = init(property);
    }
    return v[property].promise(); 
  };

  return v;
})();

Using vehicle.vehicleSpeed.get() you can't do this in ES5.

Could a counter argument be that the promise for vehicle.vehicleSpeed.get() does the initialization?

[djensen47]

One way to avoid "magic strings" is to use a constant.

vehicle.subscribe(vehicleAttributes.SPEED, options, callback)

[eorroe]

@djensen47 did you read my response I kind of solved that problem. I think.

[djensen47]

Yet another idea. Doesn't really address the autocomplete but might help with "lazy loading."

var speed = vehicle.getAttribute(vehicle.SPEED);
speed.get(…);
speed.set(…);
speed.subscribe(…);
speed.unsubscribe(…);

As @tripzero mentioned on the phone getAttribute could be a promise.

[djensen47]

@eorroe I think we decided that your proposal would explode dramatically increase the quantity the number of APIs on vehicle however, we did note that vehicle.speed is better than vehicle.vehicleSpeed.

[djensen47]

Hmm, there might be a way to lazy load with the current API style. @tripzero, what do you think?

var speed, engineSpeed;
var vehicle = {};
Object.defineProperty(vehicle, "speed", {
  get: function() {
    if (!speed) {
      //initialize speed here
    }
    return speed;
  },
  set: function(val) {
    //do nothing, not allowed
  }
});

This also has the advantage of preventing set I think

[eorroe]

@djensen47 what do you mean they'll explode? It'll have to be completely rewritten??

[djensen47]

"Explode" in terms of quantity of methods on the vehicle object. You're basically putting all the methods from vehicle. into vehicle.

[eorroe]

No I said take the last one:

{
 speed: {
  get() {}, // returns car's speed
  set(newSpeed) {}, // returns a promise with the new speed
 },

 door: {
  lock() {}, // returns a promise
  unlock() {}, // returns a promise
  open() {}, // returns a promise
  close() {} // returns a promise
 }
}

[djensen47]

That's very similar to the existing API. The nice thing about the current API is that when you have a similar signature for each attribute the attribute object can inherit it's methods from a super class/object.

Methods like lock() and unlock() could be considered as well but should probably be addressed in separate issues with regard to the vehicle data interface.

[eorroe]

The reason I put lock() and unlock() was to get rid of:

vehicle.door.set({"lock" : true}, zone.driver).then(resolve, reject);

which could be done like this:

vehicle.door.lock(zone.driver); // returns promise

Now no need to use an objectand remember what properties to use (lock) and it's value (true), which essentially is the same thing as the problem with string parameters

This method naming is what I'm talking about. The only thing I can think of right now that your talking about inheriting is the get() and set() everywhere.

I'm not sure what the code looks like but I'm assuming this is what has to be done currently inside those get() and set() methods:

Example door.set(obj)

if(obj.lock) {
 // lock door
} else {
 // unlock door
}

no need for that if we have the proper method naming:

door: {
 lock() {
  // lock door
 },
 unlock() {
  // unlock door
 }
}

IMHO easier on the developer and the API. What happens when there's more options it grows all into the same function:

if(obj.open) {
 // open door
} else {
 // close door
}

Why not split it up easier on the API and developer because of auto completion and not having to remember the passed in object's properties

[djensen47]

@eorroe This issue is more about the abstraction over all of the data points, the common elements that each will share. There are exceptions, which are (or should be) covered in the data spec. vehicle.door.lock() is a good suggestion but it still needs get, subscribe, unsubscribe, available, and so on.

I would politely ask you to take a look at the vehicle data spec and file separate Github issues for each suggestion. If you would like to see door lock/unlock instead of set(status) then it is a separate issue.

[djensen47]

@tripzero I think you dropped from the call when we were discussing putting together a document about the pros and cons of the two ideas. Do you think you would have some time to create a pull request with such a document? In markdown I guess? My plate is full until after the Seattle face-to-face.

Also, in case you missed it, take a look at #37 (comment)

[tripzero]

Yes. I will try to put together something in markdown probably on this
thread...

On Wed, Jul 15, 2015 at 11:19 AM, Dave Jensen notifications@github.com
wrote:

@tripzero https://github.com/tripzero I think you dropped from the call
when we were discussing putting together a document about the pros and cons
of the two ideas. Do you think you would have some time to create a pull
request with such a document? In markdown I guess? My plate is full until
after the Seattle face-to-face.

Also, in case you missed it, take a look at #37 (comment)
#37 (comment)

—
Reply to this email directly or view it on GitHub
#37 (comment).

[plehegar]

Some thoughts on this issue after quickly scanning through it:

• the subscribe/unsubscribe use case seems like an observer (was it considered?), similar to
  http://www.w3.org/TR/dom/#mutationobserver
• Using promises seems a good idea
• You'll need to define a serializer if not defined already
  http://heycam.github.io/webidl/#idl-serializers

[tripzero]

@djensen47 I think you are correct. Overriding the get property on vehicle should allow for lazy load with the current API.

[tripzero]

@plehegar Mutantionobserver may be exactly what we want with subscribe -so long as it complies with the mutant registration act, I'm okay with it.

[wonsuk73]

@djensen47 @tripzero I would like to ping you guys for API design options and pros/cons for each of them. It would be great if you share the status of this item.

[tripzero]

I think we have concluded that the current api can work with lazy loading,
which is the major pro for changing. No api refactoring required unless
anyone has any other "gotchas".

On Wed, Jul 29, 2015, 4:24 PM Wonsuk Lee notifications@github.com wrote:

@djensen47 https://github.com/djensen47 @tripzero
https://github.com/tripzero I would like to ping you guys for API
design options and pros/cons for each of them. It would be great if you
share the status of this item.

—
Reply to this email directly or view it on GitHub
#37 (comment).

[wonsuk73]

@tripzero I think it's very important issue for our specs. So I think even you, I and @djensen47 had been agreed, it would be great if we could have feedbacks from the experts in outside at early stage of the specs. :)

@paulboyes @QingAn @tguild @djensen47 @aShinjiroUrata @gbrannonaaa What's your view on this?

[j-hashi]

Excuse me for jumping in. I'm basically agree with the signature change. Here are a few remarks:

• vehicle.unsubscribe(data, handler) wouldn't require 'data' parameter in its signature.
• Current VehicleSignalInterface has more attributes such as 'zones', 'supported', 'history' and methods such as availabilityChangedListener(). We should take the them into consider.
• Errors for undefined 'data' parameters might have to be revisited from developers' position. I think TypeError exception is suitable and gives a consistent way for handling them but there also might be other ways (rejecting promise or returning 0, null, invalid handle etc).

[tripzero]

@wonsuk73 so do we still need a pro/con document so that we can get outside feedback?

[wonsuk73]

@tripzero Yes! That's my opinion! What do you think?

[aShinjiroUrata]

it would be great if we could have feedbacks from the experts in outside at early stage of the specs. :)

I agree.

[QingAn]

I support we get feedbacks from the experts in outside.

[gbrannonaaa]

Agreed.
Outside expertise on this would be beneficial.

[paulboyes]

I just entered an issue (w3ctag/design-reviews#81) on TAGs spec-reviews repo on GitHub.

Please take a look and add comments to the issue if you would like to add more detail or clarification.

[djensen47]

I think we can close this issue when issue #72 is resolved.

[djensen47]

Closing this issue in favor of #81.