docs: define practices for third-party extensible APIs

wg-api/best-practices.md

@@ -32,6 +32,15 @@ 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?
+
+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?
+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)
+
 ### 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 +143,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.getPrivilegedSchemes().includes(scheme => scheme.scheme === 'app')) {
+  protocol.unregisterSchemeAsPrivileged('app')
+}
+protocol.registerSchemeAsPrivileged({ scheme: 'app', privileges: { standard: true } })
+protocol.updatePrivilegedScheme({ scheme: 'app', privileges: { secure: true } })
+```
+
 ## Classes
 
 ### Use a class's name as the module name