From c28340848ee3ff8e759f351cfe99b35f88c16537 Mon Sep 17 00:00:00 2001 From: Sangwhan Moon Date: Thu, 27 May 2021 20:48:43 +0900 Subject: [PATCH 1/4] Two new principles (actually one existing one recycled) for devices. #39. --- index.bs | 57 +++++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 44 insertions(+), 13 deletions(-) diff --git a/index.bs b/index.bs index aba43029..4ac50352 100644 --- a/index.bs +++ b/index.bs @@ -1962,24 +1962,55 @@ Note: While APIs should not expose a full list of devices in an [=implementation-defined=] order, they may need to for web compatibility reasons. -

Native APIs don't typically translate well to the web

+

Design based on functionality, not the underlying API or hardware

+Try to design new native capabilities being brought to the web based on functionality. -When adapting native operating system APIs for the web, -make sure the new web APIs are designed with web platform principles in mind. +You will probably not be able to directly translate +an API available to native applications +to a web API. + +Instead, consider the functionality available from the native API, +and the user needs it addresses, +and design an API that meets those user needs, +even if the implementation depends on the existing native API. + +Be particularly careful about exposing +the exact lifecycle and data structures of the underlying native APIs. +When possible, consider flexibility for new hardware. + +This means newly proposed APIs should be designed +with careful consideration on how they are intended to be used +rather than the underlying hardware, device, or native API +available today. + +

Be proactive about safety

- : Design based on functionality, not based on the existing API - :: You will probably not be able to directly translate - an API available to native applications - to be a web API. +When bringing native capabilities to the web platform, +try to design defensively. - Instead, consider the functionality available from the native API, - and the user needs it addresses, - and design an API which meets those user needs, - even if the implmentation depends on the existing native API. +Bringing a native capability to the web platform +comes with many implications. +Users may not want websites to know that their computers +have specific capabilities. Therefore, access to anything +outside of the logical origin boundary should be permission gated. - Be particularly careful about exposing - the exact lifecycle and data structures of the underlying native APIs. +For example, if a device can store state, +and that state is readable at the same time by multiple origins, +a set of APIs that lets you read and write that state +is effectively a side-channel that undermines the origin model of the web. + +For these reasons, even if the device allows non-exclusive access, +you may want to consider enforcing exclusive access per-origin, +or even restricting it further to only the current active tab. + +Additionally, APIs should be designed so that the applications +can gracefully handle physical disruption, such as a device being unplugged. + +

Native APIs don't typically translate well to the web

+ +When adapting native operating system APIs for the web, +make sure the new web APIs are designed with web platform principles in mind. : Make sure the web API can be implemented on more than one platform :: When designing a wrapper API, From 9e362fcb0272f55eafc21bef4fbaf018d6d0f009 Mon Sep 17 00:00:00 2001 From: "Sangwhan \"fish\" Moon" Date: Wed, 15 Sep 2021 17:06:09 +0900 Subject: [PATCH 2/4] Update index.bs Co-authored-by: Daniel Appelquist --- index.bs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.bs b/index.bs index 4ac50352..af7f4ff4 100644 --- a/index.bs +++ b/index.bs @@ -1964,7 +1964,7 @@ they may need to for web compatibility reasons.

Design based on functionality, not the underlying API or hardware

-Try to design new native capabilities being brought to the web based on functionality. +Design new native capabilities being brought to the web based on functionality. You will probably not be able to directly translate an API available to native applications From bd418b75bf418ea3ea4c960f9fc3c74248ecc5be Mon Sep 17 00:00:00 2001 From: "Sangwhan \"fish\" Moon" Date: Wed, 15 Sep 2021 17:07:56 +0900 Subject: [PATCH 3/4] Update index.bs --- index.bs | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/index.bs b/index.bs index af7f4ff4..da5c8e08 100644 --- a/index.bs +++ b/index.bs @@ -1966,14 +1966,12 @@ they may need to for web compatibility reasons. Design new native capabilities being brought to the web based on functionality. -You will probably not be able to directly translate -an API available to native applications -to a web API. +Avoid directly translating an existing native API to the web. Instead, consider the functionality available from the native API, and the user needs it addresses, and design an API that meets those user needs, -even if the implementation depends on the existing native API. +even as the implementation depends on the existing native API. Be particularly careful about exposing the exact lifecycle and data structures of the underlying native APIs. @@ -1981,7 +1979,7 @@ When possible, consider flexibility for new hardware. This means newly proposed APIs should be designed with careful consideration on how they are intended to be used -rather than the underlying hardware, device, or native API +rather than how the underlying hardware, device, or native API available today.

Be proactive about safety

From abd88328c4863836349ebdbd3e1b5ee676414b88 Mon Sep 17 00:00:00 2001 From: "Sangwhan \"fish\" Moon" Date: Wed, 15 Sep 2021 17:13:26 +0900 Subject: [PATCH 4/4] Update index.bs --- index.bs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.bs b/index.bs index da5c8e08..137cfa38 100644 --- a/index.bs +++ b/index.bs @@ -1971,7 +1971,7 @@ Avoid directly translating an existing native API to the web. Instead, consider the functionality available from the native API, and the user needs it addresses, and design an API that meets those user needs, -even as the implementation depends on the existing native API. +even if the implementation depends on the existing native API. Be particularly careful about exposing the exact lifecycle and data structures of the underlying native APIs.