[wake-lock] TAG feedback on wake-lock API

travisleithead has just created a new issue for 
https://github.com/w3c/wake-lock:

== TAG feedback on wake-lock API ==
Hi,

As requested (https://github.com/w3ctag/spec-reviews/issues/126), the 
TAG has reviewed the wake-lock API, and I have the pleasure of 
conveying our comments! Note that we may have additional feedback 
coming, but to make the deadline noted in the request for feedback, 
we're submitting what we have so far.

As always, this feedback is **not** to be taken as mandatory, but 
these are suggestions we offer with the perspective of an overall view
 of web architecture, and hope that they are useful to your group.

Initial read/review comments:

1. Great use cases document--made it clear why the feature is needed 
and important!
2. The API is a simple Boolean property. As such, it has graceful 
fallback for user agents that don't intend to support it (setting the 
property when the property does not exist does not cause an exception 
to program control flow). This is a strong benefit of the current 
design.
3. Conversely, as a simple Boolean property, there is no ability to 
extend the feature (if needed). For example, if the application would 
like to specify some kind of timeout period, then a new property would
 need to be added (this is not bad per-se, just that the functionality
 could not be conveniently combined into a single API call). Such 
things are generally extended through dictionaries, and there's no way
 to provide a dictionary to a Boolean property.
4. Since the property only corresponds to the request for the wake 
lock, there is no mechanism provided to discover if the wake lock 
request succeeded or failed--e.g., is wake lock actually going to be 
applied. IMO this lack of awareness on behalf of the application is OK
 because (in the case that the lock cannot be applied for some reason)
 the app is no worse off than the current status-quo in user agents 
today.
5. The Lifecycle model of the wake lock is well-described--nice work.
6. Section 7 (and other relevant sections) allow large latitude for 
user agents to take environmental factors into play when granting or 
revoking a wake lock. This is appropriate.

Follow-up discussion:

The TAG had a follow-up discussion that focused on two aspects of the 
API. First, was the point made above (point 4). Many APIs in the 
platform will hide implementation details, but most offer some kind of
 status of the underlying request. For example, when requesting other 
functionality like fullscreen, pointer lock, user media access, etc., 
the platform APIs are setup to provide feedback to the developer that 
the request succeeded or failed or more generally what the actual 
requested state is. We debated the use cases for how a developer would
 react if thy could know the actual wake-lock state, and so the 
position taken in this spec is justifiable. However, the approach 
taken by this API (unobservable actual wake-lock state) was such that 
it was very noticeably different.

The second aspect of the design was scrutiny of the syntax used: a 
Boolean property. After some thought we were concerned that the 
Boolean property doesn't quite fit the "shape" that web developers 
might expect from the web platform, given other request-like features.
 Once again, drawing on requestFullscreen() and requestPointerLock() 
as examples.

Taken together these two aspects of the design really pushed us toward
 recommending a functional request syntax, with events used to convey 
the wake-lock state changes. This really matches the patterns we see 
in other related APIs.

As noted, we may have more follow-up feedback coming.

Please view or discuss this issue at 
https://github.com/w3c/wake-lock/issues/85 using your GitHub account

Received on Thursday, 1 September 2016 00:15:36 UTC