Add CatalogApi.getLocations

Signed-off-by: Boris Bera <bbera@coveo.com>

.changeset/yellow-cows-tickle.md

@@ -0,0 +1,7 @@
+---
+'@backstage/catalog-client': minor
+'@backstage/plugin-catalog-react': minor
+'@backstage/plugin-catalog-node': minor
+---
+
+Add `getLocations` method to `CatalogApi` and `CatalogClient`. This method calls the [`GET /locations`](https://backstage.io/docs/features/software-catalog/software-catalog-api/#get-locations) endpoint from the catalog backend.

packages/catalog-client/report-testUtils.api.md

@@ -53,6 +53,8 @@ export class InMemoryCatalogClient implements CatalogApi {
   // (undocumented)
   getLocationByRef(_locationRef: string): Promise<Location_2 | undefined>;
   // (undocumented)
+  getLocations(): Promise<Location_2[]>;
+  // (undocumented)
   queryEntities(request?: QueryEntitiesRequest): Promise<QueryEntitiesResponse>;
   // (undocumented)
   refreshEntity(_entityRef: string): Promise<void>;

packages/catalog-client/report.api.md

@@ -62,6 +62,7 @@ export interface CatalogApi {
     locationRef: string,
     options?: CatalogRequestOptions,
   ): Promise<Location_2 | undefined>;
+  getLocations(options?: CatalogRequestOptions): Promise<Location_2[]>;
   queryEntities(
     request?: QueryEntitiesRequest,
     options?: CatalogRequestOptions,
@@ -136,6 +137,7 @@ export class CatalogClient implements CatalogApi {
     locationRef: string,
     options?: CatalogRequestOptions,
   ): Promise<Location_2 | undefined>;
+  getLocations(options?: CatalogRequestOptions): Promise<Location_2[]>;
   queryEntities(
     request?: QueryEntitiesRequest,
     options?: CatalogRequestOptions,

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

@@ -24,6 +24,7 @@ import {
   QueryEntitiesResponse,
 } from './types/api';
 import { DiscoveryApi } from './types/discovery';
+import { GetLocations200ResponseInner } from './schema/openapi';
 
 const server = setupServer();
 const token = 'fake-token';
@@ -593,6 +594,86 @@ describe('CatalogClient', () => {
     });
   });
 
+  describe('getLocations', () => {
+    const defaultResponse = [
+      {
+        data: {
+          id: '42',
+          type: 'url',
+          target: 'https://example.com',
+        },
+      },
+      {
+        data: {
+          id: '43',
+          type: 'url',
+          target: 'https://example.com',
+        },
+      },
+    ] satisfies GetLocations200ResponseInner[];
+
+    beforeEach(() => {
+      server.use(
+        rest.get(`${mockBaseUrl}/locations`, (_, res, ctx) => {
+          return res(ctx.json(defaultResponse));
+        }),
+      );
+    });
+
+    it('should return locations from correct endpoint', async () => {
+      const response = await client.getLocations({ token });
+      expect(response).toEqual([
+        {
+          id: '42',
+          type: 'url',
+          target: 'https://example.com',
+        },
+        {
+          id: '43',
+          type: 'url',
+          target: 'https://example.com',
+        },
+      ]);
+    });
+
+    it('should return empty list with empty result', async () => {
+      server.use(
+        rest.get(`${mockBaseUrl}/locations`, (_, res, ctx) => {
+          return res(ctx.json([]));
+        }),
+      );
+
+      const response = await client.getLocations({ token });
+      expect(response).toEqual([]);
+    });
+
+    it('should forward token', async () => {
+      expect.assertions(1);
+
+      server.use(
+        rest.get(`${mockBaseUrl}/locations`, (req, res, ctx) => {
+          expect(req.headers.get('authorization')).toBe(`Bearer ${token}`);
+          return res(ctx.json(defaultResponse));
+        }),
+      );
+
+      await client.getLocations({ token });
+    });
+
+    it('should not forward token if omitted', async () => {
+      expect.assertions(1);
+
+      server.use(
+        rest.get(`${mockBaseUrl}/locations`, (req, res, ctx) => {
+          expect(req.headers.get('authorization')).toBeNull();
+          return res(ctx.json(defaultResponse));
+        }),
+      );
+
+      await client.getLocations();
+    });
+  });
+
   describe('getLocationById', () => {
     const defaultResponse = {
       data: {

packages/catalog-client/src/CatalogClient.ts

@@ -75,6 +75,16 @@ export class CatalogClient implements CatalogApi {
     );
   }
 
+  /**
+   * {@inheritdoc CatalogApi.getLocations}
+   */
+  async getLocations(options?: CatalogRequestOptions): Promise<Location[]> {
+    const res = await this.requestRequired(
+      await this.apiClient.getLocations({}, options),
+    );
+    return res.map(item => item.data);
+  }
+
   /**
    * {@inheritdoc CatalogApi.getLocationById}
    */

packages/catalog-client/src/testUtils/InMemoryCatalogClient.ts

@@ -228,6 +228,10 @@ export class InMemoryCatalogClient implements CatalogApi {
     };
   }
 
+  async getLocations(): Promise<Location[]> {
+    throw new NotImplementedError('Method not implemented.');
+  }
+
   async getLocationById(_id: string): Promise<Location | undefined> {
     throw new NotImplementedError('Method not implemented.');
   }

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

@@ -590,6 +590,13 @@ export interface CatalogApi {
 
   // Locations
 
+  /**
+   * List locations
+   *
+   * @param options - Additional options
+   */
+  getLocations(options?: CatalogRequestOptions): Promise<Location[]>;
+
   /**
    * Gets a registered location by its ID.
    *

plugins/catalog-node/report-testUtils.api.md

@@ -74,6 +74,10 @@ export interface CatalogServiceMock extends CatalogService, CatalogApi {
     options?: CatalogServiceRequestOptions | CatalogRequestOptions,
   ): Promise<Location_2 | undefined>;
   // (undocumented)
+  getLocations(
+    options?: CatalogServiceRequestOptions | CatalogRequestOptions,
+  ): Promise<Location_2[]>;
+  // (undocumented)
   queryEntities(
     request?: QueryEntitiesRequest,
     options?: CatalogServiceRequestOptions | CatalogRequestOptions,

plugins/catalog-node/report.api.md

@@ -164,6 +164,8 @@ export interface CatalogService {
     options: CatalogServiceRequestOptions,
   ): Promise<Location_2 | undefined>;
   // (undocumented)
+  getLocations(options: CatalogServiceRequestOptions): Promise<Location_2[]>;
+  // (undocumented)
   queryEntities(
     request: QueryEntitiesRequest | undefined,
     options: CatalogServiceRequestOptions,

plugins/catalog-node/src/catalogService.ts

@@ -96,6 +96,8 @@ export interface CatalogService {
     options: CatalogServiceRequestOptions,
   ): Promise<GetEntityFacetsResponse>;
 
+  getLocations(options: CatalogServiceRequestOptions): Promise<Location[]>;
+
   getLocationById(
     id: string,
     options: CatalogServiceRequestOptions,
@@ -223,6 +225,12 @@ class DefaultCatalogService implements CatalogService {
     );
   }
 
+  async getLocations(
+    options: CatalogServiceRequestOptions,
+  ): Promise<Location[]> {
+    return this.#catalogApi.getLocations(await this.#getOptions(options));
+  }
+
   async getLocationById(
     id: string,
     options: CatalogServiceRequestOptions,

plugins/catalog-node/src/testUtils/catalogServiceMock.ts

@@ -95,6 +95,7 @@ export namespace catalogServiceMock {
     removeEntityByUid: jest.fn(),
     refreshEntity: jest.fn(),
     getEntityFacets: jest.fn(),
+    getLocations: jest.fn(),
     getLocationById: jest.fn(),
     getLocationByRef: jest.fn(),
     addLocation: jest.fn(),

plugins/catalog-node/src/testUtils/types.ts

@@ -90,6 +90,10 @@ export interface CatalogServiceMock extends CatalogService, CatalogApi {
     options?: CatalogServiceRequestOptions | CatalogRequestOptions,
   ): Promise<GetEntityFacetsResponse>;
 
+  getLocations(
+    options?: CatalogServiceRequestOptions | CatalogRequestOptions,
+  ): Promise<Location[]>;
+
   getLocationById(
     id: string,
     options?: CatalogServiceRequestOptions | CatalogRequestOptions,

plugins/catalog-react/src/testUtils/catalogApiMock.ts

@@ -94,6 +94,7 @@ export namespace catalogApiMock {
     removeEntityByUid: jest.fn(),
     refreshEntity: jest.fn(),
     getEntityFacets: jest.fn(),
+    getLocations: jest.fn(),
     getLocationById: jest.fn(),
     getLocationByRef: jest.fn(),
     addLocation: jest.fn(),