Merge pull request #9560 from backstage/freben/location-by-ref

Removed `CatalogApi.geLocationByEntity` and `CatalogApi.getOriginLocationByEntity`, and replaced them with `CatalogApi.getLocationByRef`.

packages/catalog-client/api-report.md

@@ -43,16 +43,12 @@ export interface CatalogApi {
     name: EntityName,
     options?: CatalogRequestOptions,
   ): Promise<Entity | undefined>;
-  getLocationByEntity(
-    entity: Entity,
-    options?: CatalogRequestOptions,
-  ): Promise<Location_2 | undefined>;
   getLocationById(
     id: string,
     options?: CatalogRequestOptions,
   ): Promise<Location_2 | undefined>;
-  getOriginLocationByEntity(
-    entity: Entity,
+  getLocationByRef(
+    locationRef: string,
     options?: CatalogRequestOptions,
   ): Promise<Location_2 | undefined>;
   refreshEntity(
@@ -95,6 +91,7 @@ export class CatalogClient implements CatalogApi {
     compoundName: EntityName,
     options?: CatalogRequestOptions,
   ): Promise<Entity | undefined>;
+  // @deprecated (undocumented)
   getLocationByEntity(
     entity: Entity,
     options?: CatalogRequestOptions,
@@ -103,6 +100,11 @@ export class CatalogClient implements CatalogApi {
     id: string,
     options?: CatalogRequestOptions,
   ): Promise<Location_2 | undefined>;
+  getLocationByRef(
+    locationRef: string,
+    options?: CatalogRequestOptions,
+  ): Promise<Location_2 | undefined>;
+  // @deprecated (undocumented)
   getOriginLocationByEntity(
     entity: Entity,
     options?: CatalogRequestOptions,

packages/catalog-client/src/CatalogClient.ts

@@ -246,7 +246,7 @@ export class CatalogClient implements CatalogApi {
   }
 
   /**
-   * {@inheritdoc CatalogApi.getOriginLocationByEntity}
+   * @deprecated please use getLocationByRef instead
    */
   async getOriginLocationByEntity(
     entity: Entity,
@@ -268,7 +268,7 @@ export class CatalogClient implements CatalogApi {
   }
 
   /**
-   * {@inheritdoc CatalogApi.getLocationByEntity}
+   * @deprecated please use getLocationByRef instead
    */
   async getLocationByEntity(
     entity: Entity,
@@ -288,6 +288,23 @@ export class CatalogClient implements CatalogApi {
       .find(l => locationCompound === stringifyLocationRef(l));
   }
 
+  /**
+   * {@inheritdoc CatalogApi.getLocationByRef}
+   */
+  async getLocationByRef(
+    locationRef: string,
+    options?: CatalogRequestOptions,
+  ): Promise<Location | undefined> {
+    const all: { data: Location }[] = await this.requestRequired(
+      'GET',
+      '/locations',
+      options,
+    );
+    return all
+      .map(r => r.data)
+      .find(l => locationRef === stringifyLocationRef(l));
+  }
+
   /**
    * {@inheritdoc CatalogApi.removeLocationById}
    */

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

@@ -262,24 +262,13 @@ export interface CatalogApi {
   ): Promise<Location | undefined>;
 
   /**
-   * Gets origin location by Entity.
+   * Gets a registered location by its ref.
    *
-   * @param entity - An {@link catalog-model#Entity}.
+   * @param locationRef - A location ref, e.g. "url:https://github.com/..."
    * @param options - Additional options
    */
-  getOriginLocationByEntity(
-    entity: Entity,
-    options?: CatalogRequestOptions,
-  ): Promise<Location | undefined>;
-
-  /**
-   * Gets Location by Entity.
-   *
-   * @param entity - An {@link catalog-model#Entity}.
-   * @param options - Additional options
-   */
-  getLocationByEntity(
-    entity: Entity,
+  getLocationByRef(
+    locationRef: string,
     options?: CatalogRequestOptions,
   ): Promise<Location | undefined>;