docs: define practices for third-party extensible APIs

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