diff --git a/.changeset/silver-books-clean.md b/.changeset/silver-books-clean.md new file mode 100644 index 0000000000..9685cc2119 --- /dev/null +++ b/.changeset/silver-books-clean.md @@ -0,0 +1,5 @@ +--- +'@backstage/catalog-client': patch +--- + +Add support for passing paging parameters to the getEntities call of the catalog client diff --git a/packages/catalog-client/api-report.md b/packages/catalog-client/api-report.md index e16ca740f6..88c5ad6c27 100644 --- a/packages/catalog-client/api-report.md +++ b/packages/catalog-client/api-report.md @@ -121,6 +121,9 @@ export type CatalogEntitiesRequest = { | Record | undefined; fields?: string[] | undefined; + offset?: number; + limit?: number; + after?: string; }; // @public diff --git a/packages/catalog-client/src/CatalogClient.test.ts b/packages/catalog-client/src/CatalogClient.test.ts index d2db98bb25..1331f8e874 100644 --- a/packages/catalog-client/src/CatalogClient.test.ts +++ b/packages/catalog-client/src/CatalogClient.test.ts @@ -175,6 +175,24 @@ describe('CatalogClient', () => { { apiVersion: '2' }, ]); }); + + it('builds paging parameters properly', async () => { + expect.assertions(2); + + server.use( + rest.get(`${mockBaseUrl}/entities`, (req, res, ctx) => { + expect(req.url.search).toBe('?offset=1&limit=2&after=%3D'); + return res(ctx.json([])); + }), + ); + + const response = await client.getEntities( + { offset: 1, limit: 2, after: '=' }, + { token }, + ); + + expect(response.items).toEqual([]); + }); }); describe('getLocationById', () => { diff --git a/packages/catalog-client/src/CatalogClient.ts b/packages/catalog-client/src/CatalogClient.ts index 29d01fbe5c..0e5e2600bb 100644 --- a/packages/catalog-client/src/CatalogClient.ts +++ b/packages/catalog-client/src/CatalogClient.ts @@ -110,7 +110,7 @@ export class CatalogClient implements CatalogApi { request?: CatalogEntitiesRequest, options?: CatalogRequestOptions, ): Promise> { - const { filter = [], fields = [] } = request ?? {}; + const { filter = [], fields = [], offset, limit, after } = request ?? {}; const filterItems = [filter].flat(); const params: string[] = []; @@ -141,6 +141,16 @@ export class CatalogClient implements CatalogApi { params.push(`fields=${fields.map(encodeURIComponent).join(',')}`); } + if (offset !== undefined) { + params.push(`offset=${offset}`); + } + if (limit !== undefined) { + params.push(`limit=${limit}`); + } + if (after !== undefined) { + params.push(`after=${encodeURIComponent(after)}`); + } + const query = params.length ? `?${params.join('&')}` : ''; const entities: Entity[] = await this.requestRequired( 'GET', diff --git a/packages/catalog-client/src/types/api.ts b/packages/catalog-client/src/types/api.ts index 6344caff7c..3a09e14d71 100644 --- a/packages/catalog-client/src/types/api.ts +++ b/packages/catalog-client/src/types/api.ts @@ -29,11 +29,81 @@ export const CATALOG_FILTER_EXISTS = Symbol('CATALOG_FILTER_EXISTS'); * @public */ export type CatalogEntitiesRequest = { + /** + * If given, return only entities that match the given patterns. + * + * @remarks + * + * If multiple filter sets are given as an array, then there is effectively an + * OR between each filter set. + * + * Within one filter set, there is effectively an AND between the various + * keys. + * + * Within one key, if there are more than one value, then there is effectively + * an OR between them. + * + * Example: For an input of + * + * ``` + * [ + * { kind: ['API', 'Component'] }, + * { 'metadata.name': 'a', 'metadata.namespace': 'b' } + * ] + * ``` + * + * This effectively means + * + * ``` + * (kind = EITHER 'API' OR 'Component') + * OR + * (metadata.name = 'a' AND metadata.namespace = 'b' ) + * ``` + * + * Each key is a dot separated path in each object. + * + * As a value you can also pass in the symbol `CATALOG_FILTER_EXISTS` + * (exported from this package), which means that you assert on the existence + * of that key, no matter what its value is. + */ filter?: | Record[] | Record | undefined; + /** + * If given, return only the parts of each entity that match those dot + * separated paths in each object. + * + * @remarks + * + * Example: For an input of `['kind', 'metadata.annotations']`, then response + * objects will be shaped like + * + * ``` + * { + * "kind": "Component", + * "metadata": { + * "annotations": { + * "foo": "bar" + * } + * } + * } + * ``` + */ fields?: string[] | undefined; + /** + * If given, skips over the first N items in the result set. + */ + offset?: number; + /** + * If given, returns at most N items from the result set. + */ + limit?: number; + /** + * If given, skips over all items before that cursor as returned by a previous + * request. + */ + after?: string; }; /**