Merge pull request #32345 from backstage/rugvip/restrict

frontend-app-api: restrict the ability for plugins to override APIs

docs/frontend-system/building-plugins/01-index.md

@@ -124,7 +124,7 @@ export interface ExampleApi {
 }
 
 export const exampleApiRef = createApiRef<ExampleApi>({
-  id: 'plugin.example',
+  id: 'plugin.example.api',
 });
 
 export class DefaultExampleApi implements ExampleApi {

docs/frontend-system/utility-apis/02-creating.md

@@ -36,6 +36,9 @@ export const workApiRef = createApiRef<WorkApi>({
 
 Both of these are properly exported publicly from the package, so that consumers can reach them.
 
+The frontend system infers the owning plugin for an API from the `ApiRef` id, so
+use the pattern `plugin.<plugin-id>.*` to make ownership explicit. This ensures that other plugins can't mistakenly override your API.
+
 ## Providing an extension through your plugin
 
 The plugin itself now wants to provide this API and its default implementation, in the form of an API extension. Doing so means that when users install the Example plugin, an instance of the Work utility API will also be automatically available in their apps - both to the Example plugin itself, and to others. We do this in the main plugin package, not the `-react` package.

docs/frontend-system/utility-apis/04-configuring.md

@@ -36,6 +36,8 @@ Well written input-enabled extension often have extension creator functions that
 
 Like with other extension types, you replace Utility APIs with your own custom implementation using [extension overrides](../architecture/25-extension-overrides.md).
 
+Note that it is only possible to override a Utility API using a module for the plugin that originally provided the API. Attempting to override an API using a different plugin or module for a different plugin will result in a conflict error.
+
 ```tsx title="in your app"
 /* highlight-add-start */
 import { createFrontendModule } from '@backstage/frontend-plugin-api';