From 000190de69035e5cd92eb7f20c70c2401bb52f54 Mon Sep 17 00:00:00 2001
From: Patrik Oldsberg <poldsberg@gmail.com>
Date: Wed, 17 Nov 2021 11:48:42 +0100
Subject: [PATCH] changesets: add changeset for ApiRegistry deprecation

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>
---
 .changeset/wet-seas-deliver.md | 63 ++++++++++++++++++++++++++++++++++
 1 file changed, 63 insertions(+)
 create mode 100644 .changeset/wet-seas-deliver.md

diff --git a/.changeset/wet-seas-deliver.md b/.changeset/wet-seas-deliver.md
new file mode 100644
index 0000000000..0b440cbb46
--- /dev/null
+++ b/.changeset/wet-seas-deliver.md
@@ -0,0 +1,63 @@
+---
+'@backstage/core-app-api': patch
+'@backstage/test-utils': patch
+---
+
+The `ApiRegistry` from `@backstage/core-app-api` class has been deprecated and will be removed in a future release. To replace it, we have introduced two new helpers that are exported from `@backstage/test-utils`, namely `TestApiProvider` and `TestApiRegistry`.
+
+These two new helpers are more tailored for writing tests and development setups, as they allow for partial implementations of each of the APIs.
+
+When migrating existing code it is typically best to prefer usage of `TestApiProvider` when possible, so for example the following code:
+
+```tsx
+render(
+  <ApiProvider
+    apis={ApiRegistry.from([
+      [identityApiRef, mockIdentityApi as unknown as IdentityApi]
+    ])}
+  >
+    {...}
+  </ApiProvider>
+)
+```
+
+Would be migrated to this:
+
+```tsx
+render(
+  <TestApiProvider apis={[[identityApiRef, mockIdentityApi]]}>
+    {...}
+  </TestApiProvider>
+)
+```
+
+In cases where the `ApiProvider` is used in a more standalone way, for example to reuse a set of APIs across multiple tests, the `TestApiRegistry` can be used instead. Note that the `TestApiRegistry` only has a single static factory method, `.with()`, and it is slightly different from the existing `.with()` method on `ApiRegistry`.
+
+Usage that looks like this:
+
+```ts
+const apis = ApiRegistry.with(
+  identityApiRef,
+  mockIdentityApi as unknown as IdentityApi,
+).with(configApiRef, new ConfigReader({}));
+```
+
+OR like this:
+
+```ts
+const apis = ApiRegistry.from([
+  [identityApiRef, mockIdentityApi as unknown as IdentityApi],
+  [configApiRef, new ConfigReader({})],
+]);
+```
+
+Would be migrated to this:
+
+```ts
+const apis = TestApiRegistry.with(
+  [identityApiRef, mockIdentityApi],
+  [configApiRef, new ConfigReader({})],
+);
+```
+
+If your app is still using the `ApiRegistry` to construct the `apis` for `createApp`, we recommend that you move over to use the new method of supplying API factories instead, using `createApiFactory`.