Non privacy related design notes on device APIs

[cynthia]

While there is already a section mentioning device APIs in the document, it should have a additional section on what is expected from a device API aside from the privacy perspective. Ideas that come to mind:

• APIs should always consider that the same API (hence, same device) can/will be exposed to multiple running applications, in the open web.
• When in doubt, any direct access to a hardware device should ask the user (or OS) for permission. Installable web apps can ask at install time, otherwise this should be asked either when the call is made or via a manifest.
• APIs should always take into consideration that the user (or OS) can choose reject access to the hardware device, and design around that.
• APIs are expected to provide a mechanism for the application to gracefully handle the device resource being taken away from the application due to either the device no longer being available to the user agent (e.g. hardware unplugged) or due to the user switching tabs. (e.g. the device should/cannot be shared)
• Device APIs should follow the extensible web principles, but should be high level enough to abstract away API calls (at least the obvious cases) from potentially triggering OS/Driver level failures. (such as kernel panics)

The last item may sound a bit strange, but I've seen at least one that could potentially do this. (I don't think it has been implemented as of today, or at least publicly)

Also, not sure how to word this or articulate a model example - but there are cases where permission should be granted on a device/sub-functionality level rather than what's covered in a single spec. Or should we just trust the individual group's judgement on this and leave it out?

Something about dealing with continuity for device references, in contexts where this makes sense. (e.g. a gamepad being replugged into a different USB port should map back to the same player in a game - unfortunately this is the only example I can think of from the back of my head, but it's solved in the Gamepad API.)

[torgo]

@dbaron : some devices can be exposed simultaneously using different APIs.

@cynthia to write something.

[dbaron]

w3ctag/design-reviews#64 is a bit related to that, although there might be another related issue that I didn't see.

[cynthia]

Taken up during Tokyo F2F. Feedback from the group mentioned that some devices are exposed in multiple ways via different APIs. (e.g. output audio device control possible via multiple APIs.)

[cynthia]

Maybe 20% of this has been addressed in section 8 of the document.

@alice to ping me when the refactoring is done for me to write this later on.

[kenchris]

@anssiko @reillyeon ^ Sangwhan will start working on this soon, so keep an eye out and provide feedback

[torgo]

Suggested on today's call to try to retrieve this from the abyss and make some progress on it by holding a special breakout call in the coming weeks.

[kenchris]

Maybe something like:

When adding new APIs exposing hardware devices and sensors such as camera, gyroscope and serial devices, make sure the user is aware before such access is granted, for instance by asking permission.

Avoid exposing any devices available for access unless selected and explicitly granted by the user. For instance an API granting access to Bluetooth devices should not be able to see what devices can be accessed, such as names and IDs, unless the user has explicitly selected which device(s) to expose.

It is important to be aware that multiple sites might be able to access the same device and potentially use that for tracking, or for the two sites to communicate with each other.

Any API needs to be designed in a way that it can gracefully handle if API access, or the device itself, is being revoked/removed, at any time, by the system or the user.

Creating device APIs is a balancing act. APIs should as a guiding factor follow the extensible web principles, but at the same time not be tied to specific hardware and system implementation details. It can also be needed to lift the abstraction to a higher level due to security and privacy issues, while allowing most of the wished-for use-cases.

[cynthia]

I carefully looked at the proposed text and compared it to our OS/Device API section and it looks like we have the bases already pretty well covered (with some of the recent additions) so I think this is safe to close.