From 57585d89f926f09a52d0749e9ba7c99f876ae39a Mon Sep 17 00:00:00 2001 From: ivgo Date: Mon, 26 Jun 2023 16:36:36 +0200 Subject: [PATCH] Export more types and functions for customization Signed-off-by: ivgo --- .changeset/green-otters-wait.md | 7 ++++ .../catalog-unprocessed-entities/README.md | 24 +++++++++++ .../src/api/index.ts | 41 +++++++++++++++---- .../catalog-unprocessed-entities/src/index.ts | 10 +++++ .../src/plugin.ts | 4 +- .../catalog-unprocessed-entities/src/types.ts | 12 ++++++ 6 files changed, 87 insertions(+), 11 deletions(-) create mode 100644 .changeset/green-otters-wait.md diff --git a/.changeset/green-otters-wait.md b/.changeset/green-otters-wait.md new file mode 100644 index 0000000000..4f9b02351e --- /dev/null +++ b/.changeset/green-otters-wait.md @@ -0,0 +1,7 @@ +--- +'@backstage/plugin-catalog-unprocessed-entities': patch +--- + +Export some types and API items. This allows people to call the API from different places with the ApiRef, as well +as completely customize the client if required. Check the [README.md](../plugins/catalog-unprocessed-entities/README.md) to +note what needs to be added in order to use the new `catalogUnprocessedEntitiesApiRef` exported function. diff --git a/plugins/catalog-unprocessed-entities/README.md b/plugins/catalog-unprocessed-entities/README.md index 198d60b882..3e5e434c67 100644 --- a/plugins/catalog-unprocessed-entities/README.md +++ b/plugins/catalog-unprocessed-entities/README.md @@ -40,6 +40,30 @@ import { CatalogUnprocessedEntitiesPage } from '@backstage/plugin-catalog-unproc />; ``` +## Customization + +If you want to use the provided endpoints in a different way, you can use the ApiRef doing the following: + +```typescript +import { catalogUnprocessedEntitiesApiRef } from '@backstage/plugin-catalog-unprocessed-entities'; +import { useApi } from '@backstage/core-plugin-api'; + +const catalogUnprocessedEntitiesApi = useApi(catalogUnprocessedEntitiesApiRef); +``` + +Note that you will need to add the API implementation to avoid your instance to crash due to "missing implementation for apiRef". To do so, add the following lines: + +```typescript +// In packages/app/src/apis.ts +import { catalogUnprocessedEntitiesPlugin } from '@backstage/plugin-catalog-unprocessed-entities'; + +export const apis: AnyApiFactory[] = [ + // ...other API implementations + + ...catalogUnprocessedEntitiesPlugin.getApis(), +]; +``` + ## Getting started Your plugin has been added to the example app in this repository, meaning you'll be able to access it by running `yarn start` in the root directory, and then navigating to [/catalog-unprocessed-entities](http://localhost:3000/catalog-unprocessed-entities). diff --git a/plugins/catalog-unprocessed-entities/src/api/index.ts b/plugins/catalog-unprocessed-entities/src/api/index.ts index 5be81c8331..92dde93a93 100644 --- a/plugins/catalog-unprocessed-entities/src/api/index.ts +++ b/plugins/catalog-unprocessed-entities/src/api/index.ts @@ -32,20 +32,43 @@ export const catalogUnprocessedEntitiesApiRef = }); /** - * API client for the Catalog Unprocessed Entities plugin + * Response expected by the {@link CatalogUnprocessedEntitiesApi} * * @public */ -export class CatalogUnprocessedEntitiesApi { - url: string = ''; +export type CatalogUnprocessedEntitiesApiResponse = { + entities: UnprocessedEntity[]; +}; +/** + * Interface for the CatalogUnprocessedEntitiesApi. + * + * @public + */ +export interface CatalogUnprocessedEntitiesApi { + /** + * Returns a list of entities with state 'pending' + */ + pending(): Promise; + /** + * Returns a list of entities with state 'failed' + */ + failed(): Promise; +} + +/** + * Default API implementation for the Catalog Unprocessed Entities plugin + * + * @public + */ +export class CatalogUnprocessedEntitiesClient + implements CatalogUnprocessedEntitiesApi +{ constructor(public discovery: DiscoveryApi, public fetchApi: FetchApi) {} private async fetch(path: string, init?: RequestInit): Promise { - if (!this.url) { - this.url = await this.discovery.getBaseUrl('catalog'); - } - const resp = await this.fetchApi.fetch(`${this.url}/${path}`, init); + const url = await this.discovery.getBaseUrl('catalog'); + const resp = await this.fetchApi.fetch(`${url}/${path}`, init); if (!resp.ok) { throw await ResponseError.fromResponse(resp); } @@ -53,11 +76,11 @@ export class CatalogUnprocessedEntitiesApi { return await resp.json(); } - async pending(): Promise<{ entities: UnprocessedEntity[] }> { + async pending(): Promise { return await this.fetch('entities/unprocessed/pending'); } - async failed(): Promise<{ entities: UnprocessedEntity[] }> { + async failed(): Promise { return await this.fetch('entities/unprocessed/failed'); } } diff --git a/plugins/catalog-unprocessed-entities/src/index.ts b/plugins/catalog-unprocessed-entities/src/index.ts index 11ed24113f..4fcc9a8fcd 100644 --- a/plugins/catalog-unprocessed-entities/src/index.ts +++ b/plugins/catalog-unprocessed-entities/src/index.ts @@ -18,3 +18,13 @@ export { CatalogUnprocessedEntitiesPage, } from './plugin'; export { UnprocessedEntitiesContent } from './components/UnprocessedEntities'; +export { + type CatalogUnprocessedEntitiesApiResponse, + type CatalogUnprocessedEntitiesApi, + catalogUnprocessedEntitiesApiRef, +} from './api'; +export type { + UnprocessedEntity, + UnprocessedEntityCache, + UnprocessedEntityError, +} from './types'; diff --git a/plugins/catalog-unprocessed-entities/src/plugin.ts b/plugins/catalog-unprocessed-entities/src/plugin.ts index 14598c825b..baf7278454 100644 --- a/plugins/catalog-unprocessed-entities/src/plugin.ts +++ b/plugins/catalog-unprocessed-entities/src/plugin.ts @@ -23,7 +23,7 @@ import { import { rootRouteRef } from './routes'; import { - CatalogUnprocessedEntitiesApi, + CatalogUnprocessedEntitiesClient, catalogUnprocessedEntitiesApiRef, } from './api'; @@ -42,7 +42,7 @@ export const catalogUnprocessedEntitiesPlugin = createPlugin({ api: catalogUnprocessedEntitiesApiRef, deps: { discoveryApi: discoveryApiRef, fetchApi: fetchApiRef }, factory: ({ discoveryApi, fetchApi }) => - new CatalogUnprocessedEntitiesApi(discoveryApi, fetchApi), + new CatalogUnprocessedEntitiesClient(discoveryApi, fetchApi), }), ], }); diff --git a/plugins/catalog-unprocessed-entities/src/types.ts b/plugins/catalog-unprocessed-entities/src/types.ts index 490027b57a..65f21970f5 100644 --- a/plugins/catalog-unprocessed-entities/src/types.ts +++ b/plugins/catalog-unprocessed-entities/src/types.ts @@ -15,6 +15,10 @@ */ import { Entity } from '@backstage/catalog-model'; +/** + * Unprocessed entity data stored in the database. + * @public + */ export type UnprocessedEntity = { entity_id: string; entity_ref: string; @@ -29,11 +33,19 @@ export type UnprocessedEntity = { location_key?: string; }; +/** + * Unprocessed entity cache stored in the database. + * @public + */ export type UnprocessedEntityCache = { ttl: number; cache: object; }; +/** + * Unprocessed entity error information stored in the database. + * @public + */ export type UnprocessedEntityError = { name: string; message: string;