Leave room for pagination later on

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

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

@@ -16,6 +16,7 @@ import { GetEntityAncestorsRequest } from '@backstage/catalog-client';
 import { GetEntityAncestorsResponse } from '@backstage/catalog-client';
 import { GetEntityFacetsRequest } from '@backstage/catalog-client';
 import { GetEntityFacetsResponse } from '@backstage/catalog-client';
+import { GetLocationsResponse } from '@backstage/catalog-client';
 import { Location as Location_2 } from '@backstage/catalog-client';
 import { QueryEntitiesRequest } from '@backstage/catalog-client';
 import { QueryEntitiesResponse } from '@backstage/catalog-client';
@@ -53,7 +54,7 @@ export class InMemoryCatalogClient implements CatalogApi {
   // (undocumented)
   getLocationByRef(_locationRef: string): Promise<Location_2 | undefined>;
   // (undocumented)
-  getLocations(): Promise<Location_2[]>;
+  getLocations(_request?: {}): Promise<GetLocationsResponse>;
   // (undocumented)
   queryEntities(request?: QueryEntitiesRequest): Promise<QueryEntitiesResponse>;
   // (undocumented)

packages/catalog-client/report.api.md

@@ -62,7 +62,10 @@ export interface CatalogApi {
     locationRef: string,
     options?: CatalogRequestOptions,
   ): Promise<Location_2 | undefined>;
-  getLocations(options?: CatalogRequestOptions): Promise<Location_2[]>;
+  getLocations(
+    request?: {},
+    options?: CatalogRequestOptions,
+  ): Promise<GetLocationsResponse>;
   queryEntities(
     request?: QueryEntitiesRequest,
     options?: CatalogRequestOptions,
@@ -137,7 +140,10 @@ export class CatalogClient implements CatalogApi {
     locationRef: string,
     options?: CatalogRequestOptions,
   ): Promise<Location_2 | undefined>;
-  getLocations(options?: CatalogRequestOptions): Promise<Location_2[]>;
+  getLocations(
+    request?: {},
+    options?: CatalogRequestOptions,
+  ): Promise<GetLocationsResponse>;
   queryEntities(
     request?: QueryEntitiesRequest,
     options?: CatalogRequestOptions,
@@ -252,6 +258,12 @@ export interface GetEntityFacetsResponse {
   >;
 }
 
+// @public
+export interface GetLocationsResponse {
+  // (undocumented)
+  items: Location_2[];
+}
+
 // @public
 type Location_2 = {
   id: string;

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

@@ -621,19 +621,21 @@ describe('CatalogClient', () => {
     });
 
     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',
-        },
-      ]);
+      const response = await client.getLocations({}, { token });
+      expect(response).toEqual({
+        items: [
+          {
+            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 () => {
@@ -643,8 +645,8 @@ describe('CatalogClient', () => {
         }),
       );
 
-      const response = await client.getLocations({ token });
-      expect(response).toEqual([]);
+      const response = await client.getLocations({}, { token });
+      expect(response).toEqual({ items: [] });
     });
 
     it('should forward token', async () => {
@@ -657,7 +659,7 @@ describe('CatalogClient', () => {
         }),
       );
 
-      await client.getLocations({ token });
+      await client.getLocations({}, { token });
     });
 
     it('should not forward token if omitted', async () => {

packages/catalog-client/src/CatalogClient.ts

@@ -36,6 +36,7 @@ import {
   GetEntityAncestorsResponse,
   GetEntityFacetsRequest,
   GetEntityFacetsResponse,
+  GetLocationsResponse,
   Location,
   QueryEntitiesRequest,
   QueryEntitiesResponse,
@@ -78,11 +79,16 @@ export class CatalogClient implements CatalogApi {
   /**
    * {@inheritdoc CatalogApi.getLocations}
    */
-  async getLocations(options?: CatalogRequestOptions): Promise<Location[]> {
+  async getLocations(
+    request?: {},
+    options?: CatalogRequestOptions,
+  ): Promise<GetLocationsResponse> {
     const res = await this.requestRequired(
-      await this.apiClient.getLocations({}, options),
+      await this.apiClient.getLocations(request ?? {}, options),
     );
-    return res.map(item => item.data);
+    return {
+      items: res.map(item => item.data),
+    };
   }
 
   /**

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

@@ -28,6 +28,7 @@ import {
   GetEntityAncestorsResponse,
   GetEntityFacetsRequest,
   GetEntityFacetsResponse,
+  GetLocationsResponse,
   Location,
   QueryEntitiesRequest,
   QueryEntitiesResponse,
@@ -228,7 +229,7 @@ export class InMemoryCatalogClient implements CatalogApi {
     };
   }
 
-  async getLocations(): Promise<Location[]> {
+  async getLocations(_request?: {}): Promise<GetLocationsResponse> {
     throw new NotImplementedError('Method not implemented.');
   }
 

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

@@ -349,6 +349,15 @@ export type Location = {
   target: string;
 };
 
+/**
+ * The response type for {@link CatalogClient.getLocations}
+ *
+ * @public
+ */
+export interface GetLocationsResponse {
+  items: Location[];
+}
+
 /**
  * The request type for {@link CatalogClient.addLocation}.
  *
@@ -593,9 +602,13 @@ export interface CatalogApi {
   /**
    * List locations
    *
+   * @param request - Request parameters
    * @param options - Additional options
    */
-  getLocations(options?: CatalogRequestOptions): Promise<Location[]>;
+  getLocations(
+    request?: {},
+    options?: CatalogRequestOptions,
+  ): Promise<GetLocationsResponse>;
 
   /**
    * Gets a registered location by its ID.

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

@@ -31,6 +31,7 @@ export type {
   GetEntityAncestorsResponse,
   GetEntityFacetsRequest,
   GetEntityFacetsResponse,
+  GetLocationsResponse,
   Location,
   ValidateEntityResponse,
   QueryEntitiesCursorRequest,

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

@@ -19,6 +19,7 @@ import { GetEntityAncestorsRequest } from '@backstage/catalog-client';
 import { GetEntityAncestorsResponse } from '@backstage/catalog-client';
 import { GetEntityFacetsRequest } from '@backstage/catalog-client';
 import { GetEntityFacetsResponse } from '@backstage/catalog-client';
+import { GetLocationsResponse } from '@backstage/catalog-client';
 import { Location as Location_2 } from '@backstage/catalog-client';
 import { QueryEntitiesRequest } from '@backstage/catalog-client';
 import { QueryEntitiesResponse } from '@backstage/catalog-client';
@@ -75,8 +76,9 @@ export interface CatalogServiceMock extends CatalogService, CatalogApi {
   ): Promise<Location_2 | undefined>;
   // (undocumented)
   getLocations(
+    request?: {},
     options?: CatalogServiceRequestOptions | CatalogRequestOptions,
-  ): Promise<Location_2[]>;
+  ): Promise<GetLocationsResponse>;
   // (undocumented)
   queryEntities(
     request?: QueryEntitiesRequest,

plugins/catalog-node/report.api.md

@@ -19,6 +19,7 @@ import { GetEntityAncestorsRequest } from '@backstage/catalog-client';
 import { GetEntityAncestorsResponse } from '@backstage/catalog-client';
 import { GetEntityFacetsRequest } from '@backstage/catalog-client';
 import { GetEntityFacetsResponse } from '@backstage/catalog-client';
+import { GetLocationsResponse } from '@backstage/catalog-client';
 import { JsonValue } from '@backstage/types';
 import { Location as Location_2 } from '@backstage/catalog-client';
 import { LocationEntityV1alpha1 } from '@backstage/catalog-model';
@@ -164,7 +165,10 @@ export interface CatalogService {
     options: CatalogServiceRequestOptions,
   ): Promise<Location_2 | undefined>;
   // (undocumented)
-  getLocations(options: CatalogServiceRequestOptions): Promise<Location_2[]>;
+  getLocations(
+    request: {} | undefined,
+    options: CatalogServiceRequestOptions,
+  ): Promise<GetLocationsResponse>;
   // (undocumented)
   queryEntities(
     request: QueryEntitiesRequest | undefined,

plugins/catalog-node/src/catalogService.ts

@@ -35,6 +35,7 @@ import {
   GetEntityAncestorsResponse,
   GetEntityFacetsRequest,
   GetEntityFacetsResponse,
+  GetLocationsResponse,
   Location,
   QueryEntitiesRequest,
   QueryEntitiesResponse,
@@ -96,7 +97,10 @@ export interface CatalogService {
     options: CatalogServiceRequestOptions,
   ): Promise<GetEntityFacetsResponse>;
 
-  getLocations(options: CatalogServiceRequestOptions): Promise<Location[]>;
+  getLocations(
+    request: {} | undefined,
+    options: CatalogServiceRequestOptions,
+  ): Promise<GetLocationsResponse>;
 
   getLocationById(
     id: string,
@@ -226,9 +230,13 @@ class DefaultCatalogService implements CatalogService {
   }
 
   async getLocations(
+    request: {} | undefined,
     options: CatalogServiceRequestOptions,
-  ): Promise<Location[]> {
-    return this.#catalogApi.getLocations(await this.#getOptions(options));
+  ): Promise<GetLocationsResponse> {
+    return this.#catalogApi.getLocations(
+      request,
+      await this.#getOptions(options),
+    );
   }
 
   async getLocationById(

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

@@ -27,6 +27,7 @@ import {
   GetEntityAncestorsResponse,
   GetEntityFacetsRequest,
   GetEntityFacetsResponse,
+  GetLocationsResponse,
   Location,
   QueryEntitiesRequest,
   QueryEntitiesResponse,
@@ -91,8 +92,9 @@ export interface CatalogServiceMock extends CatalogService, CatalogApi {
   ): Promise<GetEntityFacetsResponse>;
 
   getLocations(
+    request?: {},
     options?: CatalogServiceRequestOptions | CatalogRequestOptions,
-  ): Promise<Location[]>;
+  ): Promise<GetLocationsResponse>;
 
   getLocationById(
     id: string,