ISSUE-168: getBattery() vs. requestBattery() pattern

getBattery() vs. requestBattery() pattern

State:
PENDING REVIEW
Product:
Battery Status API
Raised by:
Frederick Hirsch
Opened on:
2014-08-04
Description:
on behalf of Domenic Denicola <domenic@domenicdenicola.com>

http://lists.w3.org/Archives/Public/public-device-apis/2014Jul/0007.html

[[

The spec says

> The user agent SHOULD NOT reject the promise returned by getBattery(). If the user agent does not want to expose the battery information to the web page, it is RECOMMENDED to not expose getBattery() or resolve the promise with an instance of BatteryManager exposing only default values.

I think there has been an increasing push to make APIs use a requestAccessToX().then(gotAccess, didntGetAccess) style. Alex, CC'ed, has some reasons why this is a good pattern in general; if I recall they are around how it enables a better permissions model for apps. (I hope he can explain better.)

But just from a consistency point of view, it would make more sense to me to converge.

I realize that the default values idea might have been a result of a previous discussion that I missed, and would be happy to be pointed toward it. The "not expose getBattery()" part is kind of funny, as the spec is RECOMMENDing that implementations not comply with the spec :P

]]
Related Actions Items:
Related emails:
  1. [minutes] draft minutes from DAP 2014-08-21 call (from w3c@fjhirsch.com on 2014-08-21)
  2. [admin] Agenda - DAP Distributed Meeting 21 August 2014 (from w3c@fjhirsch.com on 2014-08-19)
  3. Re: DAP-ISSUE-169: Battery API needs to be more event driven and async, less device centric. [Battery Status API] (from anssi.kostiainen@intel.com on 2014-08-11)
  4. Re: DAP-ISSUE-168: getBattery() vs. requestBattery() pattern [Battery Status API] (from anssi.kostiainen@intel.com on 2014-08-11)
  5. dap commit: Use MUST in getBattery() prose (addresses ISSUE-168). (from cvsmail@w3.org on 2014-08-11)
  6. RE: DAP-ISSUE-168: getBattery() vs. requestBattery() pattern [Battery Status API] (from domenic@domenicdenicola.com on 2014-08-08)
  7. Re: DAP-ISSUE-168: getBattery() vs. requestBattery() pattern [Battery Status API] (from mounir@lamouri.fr on 2014-08-08)
  8. Re: DAP-ISSUE-168: getBattery() vs. requestBattery() pattern [Battery Status API] (from anssi.kostiainen@intel.com on 2014-08-08)
  9. draft minutes from today's teleconference, 7 Aug 2014 (from w3c@fjhirsch.com on 2014-08-07)
  10. [admin] Agenda - DAP Distributed Meeting 7 August 2014 (from w3c@fjhirsch.com on 2014-08-04)
  11. [battery] Battery Issue summary and status (from w3c@fjhirsch.com on 2014-08-04)
  12. DAP-ISSUE-168: getBattery() vs. requestBattery() pattern [Battery Status API] (from sysbot+tracker@w3.org on 2014-08-04)

Related notes:

http://lists.w3.org/Archives/Public/public-device-apis/2014Jul/0009.html

[[

The Battery Status API doesn't require user permission to access the
battery:
https://dvcs.w3.org/hg/dap/raw-file/tip/battery/Overview.html#security-and-privacy-considerations

]]

Frederick Hirsch, 4 Aug 2014, 19:40:36

http://lists.w3.org/Archives/Public/public-device-apis/2014Jul/0011.html

[[

> The Battery Status API doesn't require user permission to access the battery: https://dvcs.w3.org/hg/dap/raw-file/tip/battery/Overview.html#security-and-privacy-considerations

Right; in general we are pretty much done with infobar-style permission asks, as a platform. But we can still use the requestAccessToX().then(gotAccess, didntGetAccess) style even if getting access is not done as the result of an infobar. Perhaps you get access if you declare the need in a manifest, or if you're transported over HTTPS, or you get it by default but the user can toggle it off on a per-webpage basis. The user-facing API can still be uniform.

]]

Frederick Hirsch, 4 Aug 2014, 19:42:03

http://lists.w3.org/Archives/Public/public-device-apis/2014Jul/0021.html

[[

I agree, .requestWhatever() doesn't imply an info bar. Uniformity across APIs is good here. We are looking to use this pattern also in the Screen Wake Lock API.

--
Marcos Caceres

]]

Frederick Hirsch, 4 Aug 2014, 19:49:53

http://lists.w3.org/Archives/Public/public-device-apis/2014Jul/0031.html

[[
> basis. The user-facing API can still be uniform.

I don't think the requestFoo() model works very well for battery. The
API is defined in a way that if you did not get access to the battery
for the reasons listed above, we still RECOMMEND getBattery() to return
a BatteryManager with default values.

-- Mounir
]]

Frederick Hirsch, 4 Aug 2014, 19:55:33

http://lists.w3.org/Archives/Public/public-device-apis/2014Jul/0032.html

[[
> I don't think the requestFoo() model works very well for battery. The API is defined in a way that if you did not get access to the battery for the reasons listed above, we still RECOMMEND getBattery() to return a BatteryManager with default values.

Yes, I guess I was not clear. My original post was mainly about questioning whether this is a good recommendation, instead of forcing authors to handle the failure path. Thus "I realize that the default values idea might have been a result of a previous discussion that I missed, and would be happy to be pointed toward it." The name is not the important part; indeed for back-compat and reduced churn I might imagine we want to keep getBattery().

All that said, it's still worrying that the spec has RECOMMENDations instead of MUSTs for what seems like a key requirement for interop. Whichever is decided---default dummy battery, or failure path---IMO the spec should mandate one (and certainly not RECOMMEND omitting getBattery entirely).
]]

Frederick Hirsch, 4 Aug 2014, 19:56:09

http://lists.w3.org/Archives/Public/public-device-apis/2014Jul/0033.html

[[
I made a small editorial tweak to clarify this:

https://dvcs.w3.org/hg/dap/rev/cb5bbd14501b

Thanks,

-Anssi
]]

Frederick Hirsch, 4 Aug 2014, 19:57:04

http://lists.w3.org/Archives/Public/public-device-apis/2014Jul/0035.html

[[
> All that said, it's still worrying that the spec has RECOMMENDations
> instead of MUSTs for what seems like a key requirement for interop.
> Whichever is decided---default dummy battery, or failure path---IMO the
> spec should mandate one (and certainly not RECOMMEND omitting getBattery
> entirely).

The reasons were various. One is convenience. When the property was
synchronously accessible, having to check if navigator containing the
field battery could have been tiring. Another issue that this mitigates
is fingerprinting: whether you use a desktop, a fully charged laptop or
the UA doesn't want to reveal the battery information, the author will
get the same values. That mitigate the fingerprinting as much as we can
without having to go trough a permission prompt hell.

That's the approach we took when we designed this API, quite a long time
ago. Time has past and some concerns might no longer applied or be
considered as important as they used to.

-- Mounir
]]

Frederick Hirsch, 4 Aug 2014, 19:58:32

Resolved with:

https://dvcs.w3.org/hg/dap/rev/6cb6dc26210d

Frederick Hirsch, 11 Aug 2014, 19:42:26

Changelog:

Created issue 'getBattery() vs. requestBattery() pattern' nickname owned by Frederick Hirsch on product Battery Status API, description 'on behalf of Domenic Denicola <domenic@domenicdenicola.com>

http://lists.w3.org/Archives/Public/public-device-apis/2014Jul/0007.html

[[

The spec says

> The user agent SHOULD NOT reject the promise returned by getBattery(). If the user agent does not want to expose the battery information to the web page, it is RECOMMENDED to not expose getBattery() or resolve the promise with an instance of BatteryManager exposing only default values.

I think there has been an increasing push to make APIs use a requestAccessToX().then(gotAccess, didntGetAccess) style. Alex, CC'ed, has some reasons why this is a good pattern in general; if I recall they are around how it enables a better permissions model for apps. (I hope he can explain better.)

But just from a consistency point of view, it would make more sense to me to converge.

I realize that the default values idea might have been a result of a previous discussion that I missed, and would be happy to be pointed toward it. The "not expose getBattery()" part is kind of funny, as the spec is RECOMMENDing that implementations not comply with the spec :P

]]
' non-public

Frederick Hirsch, 4 Aug 2014, 19:38:42

Status changed to 'open'

Frederick Hirsch, 4 Aug 2014, 19:38:52

Status changed to 'pending review'

Frederick Hirsch, 11 Aug 2014, 19:42:26


Anssi Kostiainen <anssi.kostiainen@intel.com>, Reilly Grant <reillyg@google.com>, Chairs, Fuqiao Xue <xfq@w3.org>, Staff Contact
Tracker: documentation, (configuration for this group), originally developed by Dean Jackson, is developed and maintained by the Systems Team <w3t-sys@w3.org>.
$Id: index.php,v 1.326 2018/10/13 17:29:51 vivien Exp $