Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

@backstage/catalog-client

backstage436kApache-2.01.9.1TypeScript support: included

An isomorphic client for the catalog backend

backstage

readme

headline

Backstage

English | 한국어 | 中文版 | Français

License CNCF Status Discord Code style Codecov OpenSSF Best Practices OpenSSF Scorecard

What is Backstage?

Backstage is an open source framework for building developer portals. Powered by a centralized software catalog, Backstage restores order to your microservices and infrastructure and enables your product teams to ship high-quality code quickly without compromising autonomy.

Backstage unifies all your infrastructure tooling, services, and documentation to create a streamlined development environment from end to end.

software-catalog

Out of the box, Backstage includes:

  • Backstage Software Catalog for managing all your software such as microservices, libraries, data pipelines, websites, and ML models
  • Backstage Software Templates for quickly spinning up new projects and standardizing your tooling with your organization’s best practices
  • Backstage TechDocs for making it easy to create, maintain, find, and use technical documentation, using a "docs like code" approach
  • Plus, a growing ecosystem of open source plugins that further expand Backstage’s customizability and functionality

Backstage was created by Spotify but is now hosted by the Cloud Native Computing Foundation (CNCF) as an Incubation level project. For more information, see the announcement.

Project roadmap

For information about the detailed project roadmap including delivered milestones, see the Roadmap.

Getting Started

To start using Backstage, see the Getting Started documentation.

Documentation

The documentation of Backstage includes:

Community

To engage with our community, you can use the following resources:

Governance

See the GOVERNANCE.md document in the backstage/community repository.

License

Copyright 2020-2024 © The Backstage Authors. All rights reserved. The Linux Foundation has registered trademarks and uses trademarks. For a list of trademarks of The Linux Foundation, please see our Trademark Usage page: https://www.linuxfoundation.org/trademark-usage

Licensed under the Apache License, Version 2.0: http://www.apache.org/licenses/LICENSE-2.0

Security

Please report sensitive security issues using Spotify's bug-bounty program rather than GitHub.

For further details, see our complete security release process.

changelog

@backstage/catalog-client

1.9.1

Patch Changes

1.9.1-next.0

Patch Changes

1.9.0

Minor Changes

  • 384e494: Internal updates to generated code.

Patch Changes

1.9.0-next.2

Patch Changes

1.9.0-next.1

Minor Changes

  • 384e494: Internal updates to generated code.

Patch Changes

1.8.1-next.0

Patch Changes

1.8.0

Minor Changes

  • 656d1ef: Internal update to use the updated generated code from backstage-cli package schema openapi generate --client-package ....
  • 31c4fe0: The client now automatically splits up very large getEntitiesByRefs calls into several smaller requests behind the scenes when needed. This ensures that each individual request does not exceed common Express.js request body limits or overload the server.

Patch Changes

1.8.0-next.1

Minor Changes

  • 656d1ef: Internal update to use the updated generated code from backstage-cli package schema openapi generate --client-package ....

Patch Changes

1.8.0-next.0

Minor Changes

  • 31c4fe0: The client now automatically splits up very large getEntitiesByRefs calls into several smaller requests behind the scenes when needed. This ensures that each individual request does not exceed common Express.js request body limits or overload the server.

Patch Changes

1.7.1

Patch Changes

1.7.1-next.0

Patch Changes

1.7.0

Minor Changes

  • 78475c3: Allow offset mode paging in entity list provider
  • 29e57c7: Add catalog service mocks under the /testUtils subpath export.

Patch Changes

  • 1882cfe: Moved getEntities ordering to utilize database instead of having it inside catalog client

    Please note that the latest version of @backstage/catalog-client will not order the entities in the same way as before. This is because the ordering is now done in the database query instead of in the client. If you rely on the ordering of the entities, you may need to update your backend plugin or code to handle this change.

  • Updated dependencies

1.7.0-next.1

Minor Changes

  • 78475c3: Allow offset mode paging in entity list provider

Patch Changes

1.6.7-next.0

Patch Changes

  • 1882cfe: Moved getEntities ordering to utilize database instead of having it inside catalog client

    Please note that the latest version of @backstage/catalog-client will not order the entities in the same way as before. This is because the ordering is now done in the database query instead of in the client. If you rely on the ordering of the entities, you may need to update your backend plugin or code to handle this change.

  • Updated dependencies

1.6.6

Patch Changes

1.6.6-next.0

Patch Changes

1.6.5

Patch Changes

1.6.5-next.0

Patch Changes

1.6.4

Patch Changes

1.6.4-next.0

Patch Changes

1.6.3

Patch Changes

1.6.2

Patch Changes

1.6.1

Patch Changes

1.6.1-next.1

Patch Changes

1.6.1-next.0

Patch Changes

1.6.0

Minor Changes

  • 43dad25: Add API to get location by entity
  • 04907c3: Updates the OpenAPI specification title to plugin ID instead of package name.

Patch Changes

1.6.0-next.1

Minor Changes

  • 43dad25: Add API to get location by entity

Patch Changes

1.6.0-next.0

Minor Changes

  • 04907c3: Updates the OpenAPI specification title to plugin ID instead of package name.

Patch Changes

1.5.2

Patch Changes

1.5.2-next.0

Patch Changes

1.5.0

Minor Changes

  • 3834067: The internals of CatalogClient are now auto-generated using the backstage-repo-tools schema openapi generate-client command.

Patch Changes

1.5.0-next.1

Patch Changes

1.5.0-next.0

Minor Changes

  • 38340678c3: The internals of CatalogClient are now auto-generated using the backstage-repo-tools schema openapi generate-client command.

Patch Changes

1.4.6

Patch Changes

1.4.5

Patch Changes

1.4.5-next.0

Patch Changes

1.4.4

Patch Changes

1.4.4-next.2

Patch Changes

1.4.4-next.1

Patch Changes

1.4.4-next.0

Patch Changes

1.4.3

Patch Changes

1.4.3-next.0

Patch Changes

1.4.2

Patch Changes

1.4.2-next.2

Patch Changes

1.4.2-next.1

Patch Changes

1.4.2-next.0

Patch Changes

1.4.1

Patch Changes

1.4.1-next.1

Patch Changes

1.4.1-next.0

Patch Changes

1.4.0

Minor Changes

  • 8c030b1826c: Add queryEntities method to CatalogApi.

Patch Changes

1.4.0-next.1

Patch Changes

1.4.0-next.0

Minor Changes

  • 8c030b1826: Add queryEntities method to CatalogApi.

Patch Changes

1.3.1

Patch Changes

1.3.1-next.1

Patch Changes

1.3.1-next.0

Patch Changes

1.3.0

Minor Changes

  • f75bf76330: Implemented support for the order directive on getEntities

Patch Changes

1.3.0-next.2

Patch Changes

1.3.0-next.1

Patch Changes

1.3.0-next.0

Minor Changes

  • f75bf76330: Implemented support for the order directive on getEntities

Patch Changes

1.2.0

Minor Changes

  • 00d90b520a: BREAKING PRODUCERS: Added a new getEntitiesByRefs endpoint to CatalogApi, for efficient batch fetching of entities by ref.

Patch Changes

1.2.0-next.1

Patch Changes

1.2.0-next.0

Minor Changes

  • 00d90b520a: BREAKING PRODUCERS: Added a new getEntitiesByRefs endpoint to CatalogApi, for efficient batch fetching of entities by ref.

Patch Changes

1.1.2

Patch Changes

1.1.2-next.0

Patch Changes

1.1.1

Patch Changes

1.1.1-next.2

Patch Changes

1.1.1-next.1

Patch Changes

1.1.1-next.0

Patch Changes

1.1.0

Minor Changes

  • 65d1d4343f: Adding validateEntity method that calls /validate-entity endpoint.

Patch Changes

  • 7d47def9c4: Removed dependency on @types/jest.
  • 667d917488: Updated dependency msw to ^0.47.0.
  • 87ec2ba4d6: Updated dependency msw to ^0.46.0.
  • bf5e9030eb: Updated dependency msw to ^0.45.0.
  • ef9ab322de: Minor API signatures cleanup
  • Updated dependencies

1.1.0-next.2

Minor Changes

  • 65d1d4343f: Adding validateEntity method that calls /validate-entity endpoint.

Patch Changes

1.0.5-next.1

Patch Changes

  • 667d917488: Updated dependency msw to ^0.47.0.
  • 87ec2ba4d6: Updated dependency msw to ^0.46.0.

1.0.5-next.0

Patch Changes

  • bf5e9030eb: Updated dependency msw to ^0.45.0.
  • ef9ab322de: Minor API signatures cleanup

1.0.4

Patch Changes

1.0.4-next.2

Patch Changes

1.0.4-next.1

Patch Changes

1.0.4-next.0

Patch Changes

1.0.3

Patch Changes

  • 8f7b1835df: Updated dependency msw to ^0.41.0.
  • 35bc0a7c27: Update README to point to catalog-react for frontend usage
  • Updated dependencies

1.0.3-next.0

Patch Changes

1.0.2

Patch Changes

1.0.2-next.0

Patch Changes

1.0.1

Patch Changes

1.0.1-next.0

Patch Changes

1.0.0

Major Changes

  • b58c70c223: This package has been promoted to v1.0! To understand how this change affects the package, please check out our versioning policy.

Minor Changes

  • 0163c41be2: BREAKING: Removed the deprecated presence field in the Location and AddLocationRequest types. This field was already being ignored by the catalog backend and can be safely removed.

Patch Changes

0.9.0

Minor Changes

  • bf95bb806c: BREAKING: Removed previously deprecated CatalogApi.getEntityByName, please use getEntityByRef instead.
  • a3eb3d2afa: BREAKING: Removed CatalogClient.getLocationByEntity and CatalogClient.getOriginLocationByEntity which had previously been deprecated. Please use CatalogApi.getLocationByRef instead. Note that this only affects you if you were using CatalogClient (the class) directly, rather than CatalogApi (the interface), since it has been removed from the interface in an earlier release.

Patch Changes

0.9.0-next.0

Minor Changes

  • bf95bb806c: BREAKING: Removed previously deprecated CatalogApi.getEntityByName, please use getEntityByRef instead.
  • a3eb3d2afa: BREAKING: Removed CatalogClient.getLocationByEntity and CatalogClient.getOriginLocationByEntity which had previously been deprecated. Please use CatalogApi.getLocationByRef instead. Note that this only affects you if you were using CatalogClient (the class) directly, rather than CatalogApi (the interface), since it has been removed from the interface in an earlier release.

Patch Changes

0.8.0

Minor Changes

  • bb2ba5f10d: BREAKING: Removed the old deprecated request/response types:

    • CatalogEntitiesRequest - please use GetEntitiesRequest instead
    • CatalogEntityAncestorsRequest - please use GetEntityAncestorsRequest instead
    • CatalogEntityAncestorsResponse - please use GetEntityAncestorsResponse instead
    • CatalogListResponse - please use GetEntitiesResponse instead

Patch Changes

  • a52f69987a: DEPRECATION: Deprecated getEntityByName from CatalogApi and added getEntityByRef instead, which accepts both string and compound ref forms.
  • 36aa63022b: Use CompoundEntityRef instead of EntityName, and getCompoundEntityRef instead of getEntityName, from @backstage/catalog-model.
  • Updated dependencies

0.7.2

Patch Changes

  • ed09ad8093: Updated usage of the LocationSpec type from @backstage/catalog-model, which is deprecated.
  • 46dee04eba: Deprecated AddLocationRequest.presence, as it is already being ignored.
  • 6e1cbc12a6: Added CatalogApi.getEntityFacets. Marking this as a breaking change since it is a non-optional addition to the API and depends on the backend being in place. If you are mocking this interface in your tests, you will need to add an extra getEntityFacets: jest.fn() or similar to that interface.
  • Updated dependencies

0.7.1

Patch Changes

0.7.0

Minor Changes

  • 8eda0e7a9c: BREAKING: Removed the explicit DiscoveryApi and FetchApi export symbols, which were unnecessary duplicates from the well known core ones.

    The CATALOG_FILTER_EXISTS symbol's value has changed. However, this should not affect any code in practice.

  • deaf6065db: Removed CatalogApi.geLocationByEntity and CatalogApi.getOriginLocationByEntity, and replaced them with CatalogApi.getLocationByRef.

    If you were using one of the two old methods, you can update your code as follows:

    -const originLocation = catalogApi.getOriginLocationByEntity(entity);
+const originLocation = catalogApi.getLocationByRef(entity.metadata.annotations[ANNOTATION_ORIGIN_LOCATION]!);
-const location = catalogApi.getLocationByEntity(entity);
+const location = catalogApi.getLocationByRef(entity.metadata.annotations[ANNOTATION_LOCATION]!);

Patch Changes

  • 1ed305728b: Bump node-fetch to version 2.6.7 and cross-fetch to version 3.1.5
  • c77c5c7eb6: Added backstage.role to package.json
  • 216725b434: Updated to use new names for parseLocationRef and stringifyLocationRef
  • 244d24ebc4: Export the Location type that was previously exported by the @backstage/catalog-model package.

  • 538ca90790: Deprecated the following types used by the catalog client, and created new corresponding types to make them more consistent:

    • CatalogEntitiesRequest -> GetEntitiesRequest
    • CatalogListResponse was removed and generally replaced with GetEntitiesResponse (which does not use a type parameter argument)
    • CatalogEntityAncestorsRequest-> GetEntityAncestorsRequest
    • CatalogEntityAncestorsResponse -> GetEntityAncestorsResponse

  • 27eccab216: Replaces use of deprecated catalog-model constants.

  • Updated dependencies

0.6.0

Minor Changes

  • f8633307c4: Fixed the return type of the catalog API getEntityAncestors, to match the actual server response shape.

    While this technically is a breaking change, the old shape has never worked at all if you tried to use it - so treating this as an immediately-shipped breaking bug fix.

0.5.5

Patch Changes

0.5.5-next.0

Patch Changes

0.5.4

Patch Changes

0.5.3

Patch Changes

  • 7927005152: Add the ability to supply a custom fetchApi. In the default frontend app setup, this will use the fetchApiRef implementation.
  • 5463c03b35: Add support for passing paging parameters to the getEntities call of the catalog client

0.5.2

Patch Changes

0.5.1

Patch Changes

  • 39e92897e4: Improved API documentation for catalog-client.

0.5.0

Minor Changes

  • bb0f6b8a0f: Updates the <EntitySwitch if={asyncMethod}/> to accept asynchronous if functions.

    Adds the new getEntityAncestors method to CatalogClient.

    Updates the <EntityProcessingErrorsPanel /> to make use of the ancestry endpoint to display errors for entities further up the ancestry tree. This makes it easier to discover issues where for example the origin location has been removed or malformed.

    hasCatalogProcessingErrors() is now changed to be asynchronous so any calls outside the already established entitySwitch need to be awaited.

Patch Changes

0.4.0

Minor Changes

  • dbcaa6387a: Extends the CatalogClient interface with a refreshEntity method.

Patch Changes

0.3.19

Patch Changes

0.3.18

Patch Changes

  • 11c370af2: Support filtering entities via property existence

0.3.17

Patch Changes

  • 71c936eb6: Export CatalogRequestOptions type

0.3.16

Patch Changes

0.3.15

Patch Changes

  • ca080cab8: Don't crash if the entities response doesn't include the entities name and kind

0.3.14

Patch Changes

0.3.13

Patch Changes

0.3.12

Patch Changes

  • add62a455: Foundation for standard entity status values
  • Updated dependencies [add62a455]
  • Updated dependencies [704875e26]

0.3.11

Patch Changes

0.3.10

Patch Changes

  • 442f34b87: Make sure the CatalogClient escapes URL parameters correctly.
  • Updated dependencies [bb5055aee]
  • Updated dependencies [5d0740563]

0.3.9

Patch Changes

  • 676ede643: Added the getOriginLocationByEntity and removeLocationById methods to the catalog client
  • b196a4569: Avoid using Headers as it is not supported in the backend
  • Updated dependencies [8488a1a96]

0.3.8

Patch Changes

  • 8686eb38c: Throw the new ResponseError from @backstage/errors
  • Updated dependencies [0434853a5]

0.3.7

Patch Changes

0.3.6

Patch Changes

  • 6ed2b47d6: Include Backstage identity token in requests to backend plugins.
  • 72b96e880: Add the presence argument to the CatalogApi to be able to register optional locations.

0.3.5

Patch Changes

0.3.4

Patch Changes

0.3.3

Patch Changes

0.3.2

Patch Changes

0.3.1

Patch Changes

0.3.0

Minor Changes

  • 717e43de1: Changed the getEntities interface to (1) nest parameters in an object, (2) support field selection, and (3) return an object with an items field for future extension