Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Two new principles (actually one existing one recycled) for devices. #320

Merged
merged 4 commits into from
Sep 15, 2021
Merged

Two new principles (actually one existing one recycled) for devices. #320

Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
c283408
Two new principles (actually one existing one recycled) for devices. …
cynthia May 27, 2021
9e362fc
Update index.bs
cynthia Sep 15, 2021
bd418b7
Update index.bs
cynthia Sep 15, 2021
abd8832
Update index.bs
cynthia Sep 15, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
57 changes: 44 additions & 13 deletions index.bs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

<h3 id="wrapper-apis">Native APIs don't typically translate well to the web</h3>
<h3 id="usecase-oriented-apis">Design based on functionality, not the underlying API or hardware</h3>

Try to design new native capabilities being brought to the web based on functionality.
cynthia marked this conversation as resolved.
Show resolved Hide resolved

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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Avoid directly translating an existing native API to the web.

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.
torgo marked this conversation as resolved.
Show resolved Hide resolved

Be particularly careful about exposing
the exact lifecycle and data structures of the underlying native APIs.
torgo marked this conversation as resolved.
Show resolved Hide resolved
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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

rather than how the .... works today

available today.

<h3 id="hardware-is-scary">Be proactive about safety</h3>

: 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.

<h3 id="wrapper-apis">Native APIs don't typically translate well to the web</h3>

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,
Expand Down