From 1b04d27698f8f6b36f82c687a3a3337ddb7e535d Mon Sep 17 00:00:00 2001 From: Samuel Maddock Date: Thu, 3 Oct 2024 15:10:23 -0400 Subject: [PATCH 1/5] docs: define practices for third-party extensible APIs --- wg-api/best-practices.md | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/wg-api/best-practices.md b/wg-api/best-practices.md index db17382e7..c332b25fb 100644 --- a/wg-api/best-practices.md +++ b/wg-api/best-practices.md @@ -32,6 +32,13 @@ function whatever(opts: { a: string, b?: boolean }) { /* ... */ } See https://w3ctag.github.io/design-principles/#prefer-dict-to-bool for more details. +### Should the configured options be made extensible to third-party libraries? + +If an API accepts configuring options, should it provide the ability to append to rather than replace those options? +Would third-party libraries require special attention to API usage to avoid clobbering configured options? + +See the [style guide for designing APIs when dealing with arrays.](#provide-createreadupdatedelete-options-when-dealing-with-arrays) + ### What underlying Chromium or OS features does this API rely on? If the API you’re changing relies on underlying features provided by Chromium or by the operating system, how stable are those underlying features? How might those underlying features change in the future? @@ -134,6 +141,26 @@ Even if seconds (or some other time unit) are more natural in the domain of an A See https://w3ctag.github.io/design-principles/#milliseconds +### Provide create/read/update/delete options when dealing with arrays + +If an API is designed to accept an array of items, consider providing methods of creating, reading, updating, and deleting items. + +In the case of third-party libraries, one might want to add a single item rather than replacing existings items. + +```js +// Bad: third-party libraries can only replace registered schemes +protocol.registerSchemesAsPrivileged([ + { scheme: 'app', privileges: { standard: true } } +]) + +// Good: third-party libraries can create, read, update, and delete items +if (protocol.getRegisteredSchemes().includes(scheme => scheme.scheme === 'app')) { + protocol.unregisterScheme({ scheme: 'app' }) +} +protocol.registerScheme({ scheme: 'app', privileges: { standard: true } }) +protocol.updateScheme({ scheme: 'app', privileges: { secure: true } }) +``` + ## Classes ### Use a class's name as the module name From 1ea5033581f50d941a152f797a78e926d00e648b Mon Sep 17 00:00:00 2001 From: Sam Maddock Date: Thu, 3 Oct 2024 16:16:11 -0400 Subject: [PATCH 2/5] Update wg-api/best-practices.md Co-authored-by: Will Anderson --- wg-api/best-practices.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/wg-api/best-practices.md b/wg-api/best-practices.md index c332b25fb..b8eaf1c34 100644 --- a/wg-api/best-practices.md +++ b/wg-api/best-practices.md @@ -32,10 +32,12 @@ function whatever(opts: { a: string, b?: boolean }) { /* ... */ } See https://w3ctag.github.io/design-principles/#prefer-dict-to-bool for more details. -### Should the configured options be made extensible to third-party libraries? +### How will third-party libraries interact with this API? + +When designing an API, consider that an app might have custom code and third-party libraries that both interact with that API. Can the API be designed so that multiple callers don't interfere with each other? If an API accepts configuring options, should it provide the ability to append to rather than replace those options? -Would third-party libraries require special attention to API usage to avoid clobbering configured options? +Can third-party libraries use the API without knowing what app-specific code is also using the API? See the [style guide for designing APIs when dealing with arrays.](#provide-createreadupdatedelete-options-when-dealing-with-arrays) From e24ce5284ee3c1fc6b8663bbfa2626dd295e4cb6 Mon Sep 17 00:00:00 2001 From: Sam Maddock Date: Thu, 3 Oct 2024 16:32:00 -0400 Subject: [PATCH 3/5] Update wg-api/best-practices.md Co-authored-by: Will Anderson --- wg-api/best-practices.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/wg-api/best-practices.md b/wg-api/best-practices.md index b8eaf1c34..53d2f2ef4 100644 --- a/wg-api/best-practices.md +++ b/wg-api/best-practices.md @@ -156,11 +156,11 @@ protocol.registerSchemesAsPrivileged([ ]) // Good: third-party libraries can create, read, update, and delete items -if (protocol.getRegisteredSchemes().includes(scheme => scheme.scheme === 'app')) { - protocol.unregisterScheme({ scheme: 'app' }) +if (protocol.getPrivilegedSchemes().includes(scheme => scheme.scheme === 'app')) { + protocol.unregisterSchemeAsPrivileged('app' ) } -protocol.registerScheme({ scheme: 'app', privileges: { standard: true } }) -protocol.updateScheme({ scheme: 'app', privileges: { secure: true } }) +protocol.registerSchemeAsPrivileged({ scheme: 'app', privileges: { standard: true } }) +protocol.updatePrivilegedScheme({ scheme: 'app', privileges: { secure: true } }) ``` ## Classes From 2ac1df9bf2b76116091c0d34a1c563f6b60273d3 Mon Sep 17 00:00:00 2001 From: Samuel Maddock Date: Thu, 3 Oct 2024 16:32:39 -0400 Subject: [PATCH 4/5] extra space --- wg-api/best-practices.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/wg-api/best-practices.md b/wg-api/best-practices.md index 53d2f2ef4..599f3c795 100644 --- a/wg-api/best-practices.md +++ b/wg-api/best-practices.md @@ -157,7 +157,7 @@ protocol.registerSchemesAsPrivileged([ // Good: third-party libraries can create, read, update, and delete items if (protocol.getPrivilegedSchemes().includes(scheme => scheme.scheme === 'app')) { - protocol.unregisterSchemeAsPrivileged('app' ) + protocol.unregisterSchemeAsPrivileged('app') } protocol.registerSchemeAsPrivileged({ scheme: 'app', privileges: { standard: true } }) protocol.updatePrivilegedScheme({ scheme: 'app', privileges: { secure: true } }) From abb1350ce920006e268df42c739b7e3c28dffdd8 Mon Sep 17 00:00:00 2001 From: Samuel Maddock Date: Thu, 10 Oct 2024 14:18:03 -0400 Subject: [PATCH 5/5] mention broader component terminology --- wg-api/best-practices.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/wg-api/best-practices.md b/wg-api/best-practices.md index 599f3c795..729bc448e 100644 --- a/wg-api/best-practices.md +++ b/wg-api/best-practices.md @@ -32,7 +32,7 @@ function whatever(opts: { a: string, b?: boolean }) { /* ... */ } See https://w3ctag.github.io/design-principles/#prefer-dict-to-bool for more details. -### How will third-party libraries interact with this API? +### How will isolated components (e.g. third-party libraries) interact with this API? When designing an API, consider that an app might have custom code and third-party libraries that both interact with that API. Can the API be designed so that multiple callers don't interfere with each other? @@ -147,7 +147,7 @@ See https://w3ctag.github.io/design-principles/#milliseconds If an API is designed to accept an array of items, consider providing methods of creating, reading, updating, and deleting items. -In the case of third-party libraries, one might want to add a single item rather than replacing existings items. +In the case of isolated components (e.g. third-party libraries), one might want to add a single item rather than replacing existings items. ```js // Bad: third-party libraries can only replace registered schemes