docs: define practices for third-party extensible APIs (#586)

* docs: define practices for third-party extensible APIs

* Update wg-api/best-practices.md

Co-authored-by: Will Anderson <[email protected]>

* Update wg-api/best-practices.md

Co-authored-by: Will Anderson <[email protected]>

* extra space

* mention broader component terminology

---------

Co-authored-by: Will Anderson <[email protected]>

wg-api/best-practices.md

@@ -35,6 +35,15 @@ function whatever(opts: { a: string, b?: boolean }) { /* ... */ }
 
 See https://w3ctag.github.io/design-principles/#prefer-dict-to-bool for more details.
 
+### 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?
+
+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?
@@ -137,6 +146,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 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
+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