From 1b04d27698f8f6b36f82c687a3a3337ddb7e535d Mon Sep 17 00:00:00 2001
From: Samuel Maddock <smaddock@slack-corp.com>
Date: Thu, 3 Oct 2024 15:10:23 -0400
Subject: [PATCH] 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