feat(marketplace): add optional sorting, filtering, pagination to marketplace api

workspaces/marketplace/.changeset/quiet-kiwis-admire.md

@@ -0,0 +1,7 @@
+---
+'@red-hat-developer-hub/backstage-plugin-marketplace-backend': patch
+'@red-hat-developer-hub/backstage-plugin-marketplace-common': patch
+'@red-hat-developer-hub/backstage-plugin-marketplace': patch
+---
+
+add optional sorting, filtering, pagination to marketplace api

workspaces/marketplace/plugins/marketplace-backend/src/router.test.ts

@@ -140,7 +140,7 @@ describe('createRouter', () => {
       '/api/marketplace/plugins',
     );
     expect(response.status).toEqual(200);
-    expect(response.body).toHaveLength(2);
+    expect(response.body.items).toHaveLength(2);
   });
 
   it('should get the plugin by name', async () => {

workspaces/marketplace/plugins/marketplace-backend/src/router.ts

@@ -20,9 +20,11 @@ import Router from 'express-promise-router';
 import { HttpAuthService } from '@backstage/backend-plugin-api';
 import { InputError, NotFoundError } from '@backstage/errors';
 import {
+  decodeGetPluginsRequest,
   decodeQueryParams,
   EntityFacetSchema,
   GetEntityFacetsRequest,
+  GetPluginsRequest,
   MarketplaceApi,
   MarketplaceKinds,
 } from '@red-hat-developer-hub/backstage-plugin-marketplace-common';
@@ -36,8 +38,10 @@ export async function createRouter({
   const router = Router();
   router.use(express.json());
 
-  router.get('/plugins', async (_req, res) => {
-    const plugins = await marketplaceApi.getPlugins();
+  router.get('/plugins', async (req, res) => {
+    const query = req.url.split('?')[1] || '';
+    const request: GetPluginsRequest = decodeGetPluginsRequest(query);
+    const plugins = await marketplaceApi.getPlugins(request);
     res.json(plugins);
   });
 

workspaces/marketplace/plugins/marketplace-common/report.api.md

@@ -9,9 +9,13 @@ import { CatalogApi } from '@backstage/catalog-client';
 import { Entity } from '@backstage/catalog-model';
 import { EntityFilterQuery } from '@backstage/catalog-client';
 import { EntityFilterQuery as EntityFilterQuery_2 } from '@red-hat-developer-hub/backstage-plugin-marketplace-common';
+import { EntityOrderQuery } from '@backstage/catalog-client';
+import { EntityOrderQuery as EntityOrderQuery_2 } from '@backstage/catalog-client/index';
 import { GetEntityFacetsRequest } from '@backstage/catalog-client';
 import { GetEntityFacetsResponse } from '@backstage/catalog-client';
+import { GetPluginsRequest as GetPluginsRequest_2 } from '@red-hat-developer-hub/backstage-plugin-marketplace-common';
 import { JsonObject } from '@backstage/types';
+import { QueryEntitiesRequest } from '@backstage/catalog-client/index';
 import { z } from 'zod';
 
 // @public (undocumented)
@@ -22,12 +26,24 @@ export interface AppConfigExample extends JsonObject {
     title: string;
 }
 
+// @public (undocumented)
+export const convertGetPluginsRequestToQueryEntitiesRequest: (query?: GetPluginsRequest) => QueryEntitiesRequest;
+
 // @public (undocumented)
 export const decodeFacetParams: (searchParams: URLSearchParams) => string[];
 
 // @public (undocumented)
 export const decodeFilterParams: (searchParams: URLSearchParams) => Record<string, string[]>;
 
+// @public (undocumented)
+export const decodeGetPluginsRequest: (queryString: string) => GetPluginsRequest;
+
+// @public (undocumented)
+export const decodeOrderFields: (searchParams: URLSearchParams) => {
+    field: string;
+    order: "desc" | "asc";
+}[];
+
 // @public (undocumented)
 export const decodeQueryParams: (queryString: string) => {
     facets?: string[] | undefined;
@@ -40,6 +56,12 @@ export const encodeFacetParams: (facets: string[]) => URLSearchParams;
 // @public (undocumented)
 export const encodeFilterParams: (filter: EntityFilterQuery_2) => URLSearchParams;
 
+// @public (undocumented)
+export const encodeGetPluginsQueryParams: (options?: GetPluginsRequest_2) => URLSearchParams;
+
+// @public (undocumented)
+export const encodeOrderFieldsParams: (orderFields: EntityOrderQuery_2) => URLSearchParams;
+
 // @public (undocumented)
 export const encodeQueryParams: (options?: {
     filter?: EntityFilterQuery_2;
@@ -63,10 +85,25 @@ export { EntityFilterQuery }
 // @public (undocumented)
 export const EntityFilterQuerySchema: z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodString, "many">]>>;
 
+// @public (undocumented)
+export type FullTextFilter = {
+    term: string;
+    fields?: string[];
+};
+
 export { GetEntityFacetsRequest }
 
 export { GetEntityFacetsResponse }
 
+// @public (undocumented)
+export type GetPluginsRequest = {
+    limit?: number;
+    offset?: number;
+    filter?: EntityFilterQuery;
+    orderFields?: EntityOrderQuery;
+    searchTerm?: string;
+};
+
 // @public (undocumented)
 export enum InstallStatus {
     // (undocumented)
@@ -89,7 +126,7 @@ export interface MarketplaceApi {
     // (undocumented)
     getPluginLists(): Promise<MarketplacePluginList[]>;
     // (undocumented)
-    getPlugins(): Promise<MarketplacePlugin[]>;
+    getPlugins(request?: GetPluginsRequest): Promise<MarketplacePluginWithPageInfo>;
     // (undocumented)
     getPluginsByPluginListName(name: string): Promise<MarketplacePlugin[]>;
 }
@@ -106,7 +143,7 @@ export class MarketplaceCatalogClient implements MarketplaceApi {
     // (undocumented)
     getPluginLists(): Promise<MarketplacePluginList[]>;
     // (undocumented)
-    getPlugins(): Promise<MarketplacePlugin[]>;
+    getPlugins(request?: GetPluginsRequest): Promise<MarketplacePluginWithPageInfo>;
     // (undocumented)
     getPluginsByPluginListName(name: string): Promise<MarketplacePlugin[]>;
 }
@@ -207,4 +244,25 @@ export interface MarketplacePluginSpec extends JsonObject {
     packages?: (string | MarketplacePluginPackage)[];
 }
 
+// @public (undocumented)
+export interface MarketplacePluginWithPageInfo {
+    // (undocumented)
+    items: MarketplacePlugin[];
+    // (undocumented)
+    pageInfo?: {
+        nextCursor?: string;
+        prevCursor?: string;
+    };
+    // (undocumented)
+    totalItems?: number;
+}
+
+// @public (undocumented)
+export enum SortOrder {
+    // (undocumented)
+    asc = "asc",
+    // (undocumented)
+    desc = "desc"
+}
+
 ```

workspaces/marketplace/plugins/marketplace-common/src/api/MarketplaceCatalogClient.test.ts

@@ -94,13 +94,13 @@ describe('MarketplaceCatalogClient', () => {
     it('should return the plugins', async () => {
       const api = new MarketplaceCatalogClient(options);
       const plugins = await api.getPlugins();
-      expect(plugins).toHaveLength(2);
+      expect(plugins?.items).toHaveLength(2);
     });
 
     it('should return the plugins when the auth options is not passed', async () => {
       const api = new MarketplaceCatalogClient({ ...options, auth: undefined });
       const plugins = await api.getPlugins();
-      expect(plugins).toHaveLength(2);
+      expect(plugins?.items).toHaveLength(2);
     });
   });
 

workspaces/marketplace/plugins/marketplace-common/src/api/MarketplaceCatalogClient.ts

@@ -23,11 +23,14 @@ import {
 } from '@backstage/catalog-client';
 import { NotFoundError } from '@backstage/errors';
 import {
+  GetPluginsRequest,
   MarketplaceApi,
   MarketplaceKinds,
   MarketplacePlugin,
   MarketplacePluginList,
+  MarketplacePluginWithPageInfo,
 } from '../types';
+import { convertGetPluginsRequestToQueryEntitiesRequest } from '../utils';
 
 /**
  * @public
@@ -59,18 +62,22 @@ export class MarketplaceCatalogClient implements MarketplaceApi {
     });
   }
 
-  async getPlugins(): Promise<MarketplacePlugin[]> {
+  async getPlugins(
+    request?: GetPluginsRequest,
+  ): Promise<MarketplacePluginWithPageInfo> {
     const token = await this.getServiceToken();
+    const queryEntitiesRequest =
+      convertGetPluginsRequestToQueryEntitiesRequest(request);
     const result = await this.catalog.queryEntities(
-      {
-        filter: {
-          kind: 'plugin',
-        },
-      },
+      queryEntitiesRequest,
       token,
     );
 
-    return result.items as MarketplacePlugin[];
+    return {
+      items: result.items as MarketplacePlugin[],
+      totalItems: result.totalItems,
+      pageInfo: result.pageInfo,
+    };
   }
 
   async getPluginLists(): Promise<MarketplacePluginList[]> {

workspaces/marketplace/plugins/marketplace-common/src/types.ts

@@ -15,6 +15,8 @@
  */
 
 import {
+  EntityFilterQuery,
+  EntityOrderQuery,
   GetEntityFacetsRequest,
   GetEntityFacetsResponse,
 } from '@backstage/catalog-client';
@@ -28,6 +30,18 @@ export interface MarketplacePlugin extends Entity {
   spec?: MarketplacePluginSpec;
 }
 
+/**
+ * @public
+ */
+export interface MarketplacePluginWithPageInfo {
+  items: MarketplacePlugin[];
+  totalItems?: number;
+  pageInfo?: {
+    nextCursor?: string;
+    prevCursor?: string;
+  };
+}
+
 /**
  * @public
  */
@@ -58,6 +72,14 @@ export enum MarketplaceKinds {
   package = 'Package',
 }
 
+/**
+ * @public
+ */
+export enum SortOrder {
+  asc = 'asc',
+  desc = 'desc',
+}
+
 /**
  * @public
  */
@@ -96,6 +118,25 @@ export interface MarketplacePluginSpec extends JsonObject {
   };
 }
 
+/**
+ * @public
+ */
+export type FullTextFilter = {
+  term: string;
+  fields?: string[];
+};
+
+/**
+ * @public
+ */
+export type GetPluginsRequest = {
+  limit?: number;
+  offset?: number;
+  filter?: EntityFilterQuery;
+  orderFields?: EntityOrderQuery;
+  searchTerm?: string;
+};
+
 /**
  * @public
  */
@@ -135,7 +176,9 @@ export type {
  * @public
  */
 export interface MarketplaceApi {
-  getPlugins(): Promise<MarketplacePlugin[]>;
+  getPlugins(
+    request?: GetPluginsRequest,
+  ): Promise<MarketplacePluginWithPageInfo>;
   getPluginByName(name: string): Promise<MarketplacePlugin>;
   getPluginLists(): Promise<MarketplacePluginList[]>;
   getPluginListByName(name: string): Promise<MarketplacePluginList>;

workspaces/marketplace/plugins/marketplace-common/src/utils/decodeQueryParams.test.ts

@@ -13,13 +13,54 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+import { GetPluginsRequest } from '../types';
 import {
   decodeFacetParams,
   decodeFilterParams,
   decodeQueryParams,
+  decodeGetPluginsRequest,
+  decodeOrderFields,
 } from './decodeQueryParams';
 
 describe('decodeFilterParams', () => {
+  it('should decode single orderFields', () => {
+    const searchParams = new URLSearchParams(
+      'orderFields=metadata.title%2Casc',
+    );
+    expect(decodeOrderFields(searchParams)).toEqual([
+      { field: 'metadata.title', order: 'asc' },
+    ]);
+  });
+
+  it('should decode multiple orderFields', () => {
+    const searchParams = new URLSearchParams(
+      'orderFields=metadata.title%2Cdesc&orderFields=metadata.name%2Casc',
+    );
+    expect(decodeOrderFields(searchParams)).toEqual([
+      { field: 'metadata.title', order: 'desc' },
+      { field: 'metadata.name', order: 'asc' },
+    ]);
+  });
+
+  it('should decode GetPlugins Request', () => {
+    const encodedString =
+      'filter=metadata.name%3Dsearch&filter=spec.type%3Dbackend-plugin&orderFields=metadata.title%2Cdesc&orderFields=metadata.name%2Casc&searchTerm=search&limit=2&offset=1';
+    const params: GetPluginsRequest = {
+      filter: {
+        'metadata.name': ['search'],
+        'spec.type': ['backend-plugin'],
+      },
+      orderFields: [
+        { field: 'metadata.title', order: 'desc' },
+        { field: 'metadata.name', order: 'asc' },
+      ],
+      searchTerm: 'search',
+      limit: 2,
+      offset: 1,
+    };
+    expect(decodeGetPluginsRequest(encodedString)).toEqual(params);
+  });
+
   it('should decode single filter', () => {
     const searchParams = new URLSearchParams('filter=kind%3Dplugin');
     expect(decodeFilterParams(searchParams)).toEqual({ kind: ['plugin'] });