getEntityByName -> getEntityByRef

Signed-off-by: Fredrik Adelöw <freben@gmail.com>

.changeset/rotten-windows-worry.md

@@ -0,0 +1,5 @@
+---
+'@backstage/catalog-client': patch
+---
+
+**DEPRECATION**: Deprecated `getEntityByName` from `CatalogApi` and added `getEntityByRef` instead, which accepts both string and compound ref forms.

packages/catalog-client/api-report.md

@@ -38,10 +38,15 @@ export interface CatalogApi {
     request: GetEntityAncestorsRequest,
     options?: CatalogRequestOptions,
   ): Promise<GetEntityAncestorsResponse>;
+  // @deprecated
   getEntityByName(
     name: CompoundEntityRef,
     options?: CatalogRequestOptions,
   ): Promise<Entity | undefined>;
+  getEntityByRef(
+    entityRef: string | CompoundEntityRef,
+    options?: CatalogRequestOptions,
+  ): Promise<Entity | undefined>;
   getEntityFacets(
     request: GetEntityFacetsRequest,
     options?: CatalogRequestOptions,
@@ -94,6 +99,10 @@ export class CatalogClient implements CatalogApi {
     compoundName: CompoundEntityRef,
     options?: CatalogRequestOptions,
   ): Promise<Entity | undefined>;
+  getEntityByRef(
+    entityRef: string | CompoundEntityRef,
+    options?: CatalogRequestOptions,
+  ): Promise<Entity | undefined>;
   getEntityFacets(
     request: GetEntityFacetsRequest,
     options?: CatalogRequestOptions,

packages/catalog-client/src/CatalogClient.test.ts

@@ -195,6 +195,60 @@ describe('CatalogClient', () => {
     });
   });
 
+  describe('getEntityByRef', () => {
+    const existingEntity: Entity = {
+      apiVersion: 'v1',
+      kind: 'CustomKind',
+      metadata: {
+        namespace: 'default',
+        name: 'exists',
+      },
+    };
+
+    beforeEach(() => {
+      server.use(
+        rest.get(
+          `${mockBaseUrl}/entities/by-name/customkind/default/exists`,
+          (_, res, ctx) => {
+            return res(ctx.json(existingEntity));
+          },
+        ),
+        rest.get(
+          `${mockBaseUrl}/entities/by-name/customkind/default/missing`,
+          (_, res, ctx) => {
+            return res(ctx.status(404));
+          },
+        ),
+      );
+    });
+
+    it('finds by string and compound', async () => {
+      await expect(
+        client.getEntityByRef('customkind:default/exists'),
+      ).resolves.toEqual(existingEntity);
+      await expect(
+        client.getEntityByRef({
+          kind: 'CustomKind',
+          namespace: 'default',
+          name: 'exists',
+        }),
+      ).resolves.toEqual(existingEntity);
+    });
+
+    it('returns undefined for 404s', async () => {
+      await expect(
+        client.getEntityByRef('customkind:default/missing'),
+      ).resolves.toBeUndefined();
+      await expect(
+        client.getEntityByRef({
+          kind: 'CustomKind',
+          namespace: 'default',
+          name: 'missing',
+        }),
+      ).resolves.toBeUndefined();
+    });
+  });
+
   describe('getLocationById', () => {
     const defaultResponse = {
       data: {

packages/catalog-client/src/CatalogClient.ts

@@ -170,6 +170,27 @@ export class CatalogClient implements CatalogApi {
     return { items: entities.sort(refCompare) };
   }
 
+  /**
+   * {@inheritdoc CatalogApi.getEntityByRef}
+   */
+  async getEntityByRef(
+    entityRef: string | CompoundEntityRef,
+    options?: CatalogRequestOptions,
+  ): Promise<Entity | undefined> {
+    const { kind, namespace, name } = parseEntityRef(entityRef);
+    return this.requestOptional(
+      'GET',
+      `/entities/by-name/${encodeURIComponent(kind)}/${encodeURIComponent(
+        namespace,
+      )}/${encodeURIComponent(name)}`,
+      options,
+    );
+  }
+
+  // NOTE(freben): When we deprecate getEntityByName from the interface, we may
+  // still want to leave this implementation in place for quite some time
+  // longer, to minimize the risk for breakages. Suggested date for removal:
+  // August 2022
   /**
    * {@inheritdoc CatalogApi.getEntityByName}
    */

packages/catalog-client/src/types/api.ts

@@ -306,6 +306,20 @@ export interface CatalogApi {
    * Gets a single entity from the catalog by its ref (kind, namespace, name)
    * triplet.
    *
+   * @param entityRef - A complete entity ref, either on string or compound form
+   * @param options - Additional options
+   * @returns The matching entity, or undefined if there was no entity with that ref
+   */
+  getEntityByRef(
+    entityRef: string | CompoundEntityRef,
+    options?: CatalogRequestOptions,
+  ): Promise<Entity | undefined>;
+
+  /**
+   * Gets a single entity from the catalog by its ref (kind, namespace, name)
+   * triplet.
+   *
+   * @deprecated Use getEntityRef instead
    * @param name - A complete entity ref
    * @param options - Additional options
    */