docs: update links to point to frontend-plugin-api
Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>
This commit is contained in:
Patrik Oldsberg
+35
-35
@@ -18,23 +18,23 @@ plugins to communicate during their entire life cycle.
|
||||
|
||||
## Consuming APIs
|
||||
|
||||
Each Utility API is tied to an [`ApiRef`](../reference/core-plugin-api.apiref.md)
|
||||
Each Utility API is tied to an [`ApiRef`](../reference/frontend-plugin-api.apiref.md)
|
||||
instance, which is a global singleton object without any additional state or
|
||||
functionality, its only purpose is to reference Utility APIs.
|
||||
[`ApiRef`](../reference/core-plugin-api.apiref.md)s are created using
|
||||
[`createApiRef`](../reference/core-plugin-api.createapiref.md), which is exported
|
||||
[`ApiRef`](../reference/frontend-plugin-api.apiref.md)s are created using
|
||||
[`createApiRef`](../reference/frontend-plugin-api.createapiref.md), which is exported
|
||||
by [`@backstage/core-plugin-api`](../reference/core-plugin-api.md). There are also
|
||||
many predefined Utility APIs in
|
||||
[`@backstage/core-plugin-api`](../reference/core-plugin-api.md), and they're all
|
||||
exported with a name of the pattern `*ApiRef`, for example
|
||||
[`errorApiRef`](../reference/core-plugin-api.errorapiref.md).
|
||||
[`errorApiRef`](../reference/frontend-plugin-api.errorapiref.md).
|
||||
|
||||
To access one of the Utility APIs inside a React component, use the
|
||||
[`useApi`](../reference/core-plugin-api.useapi.md) hook exported by
|
||||
[`useApi`](../reference/frontend-plugin-api.useapi.md) hook exported by
|
||||
[`@backstage/core-plugin-api`](../reference/core-plugin-api.md), or the
|
||||
[`withApis`](../reference/core-plugin-api.withapis.md) HOC if you prefer class
|
||||
[`withApis`](../reference/frontend-plugin-api.withapis.md) HOC if you prefer class
|
||||
components. For example, the
|
||||
[`ErrorApi`](../reference/core-plugin-api.errorapi.md) can be accessed like this:
|
||||
[`ErrorApi`](../reference/frontend-plugin-api.errorapi.md) can be accessed like this:
|
||||
|
||||
```tsx
|
||||
import { useApi, errorApiRef } from '@backstage/core-plugin-api';
|
||||
@@ -52,9 +52,9 @@ export const MyComponent = () => {
|
||||
```
|
||||
|
||||
Note that there is no explicit type given for
|
||||
[`ErrorApi`](../reference/core-plugin-api.errorapi.md). This is because the
|
||||
[`errorApiRef`](../reference/core-plugin-api.errorapiref.md) has the type
|
||||
embedded, and [`useApi`](../reference/core-plugin-api.useapi.md) is able to infer
|
||||
[`ErrorApi`](../reference/frontend-plugin-api.errorapi.md). This is because the
|
||||
[`errorApiRef`](../reference/frontend-plugin-api.errorapiref.md) has the type
|
||||
embedded, and [`useApi`](../reference/frontend-plugin-api.useapi.md) is able to infer
|
||||
the type.
|
||||
|
||||
Also note that consuming Utility APIs is not limited to plugins; it can be done
|
||||
@@ -67,15 +67,15 @@ requirement is that they are beneath the `AppProvider` in the react tree.
|
||||
### API Factories
|
||||
|
||||
APIs are registered in the form of
|
||||
[`ApiFactory`](../reference/core-plugin-api.apifactory.md) instances, which encapsulate
|
||||
[`ApiFactory`](../reference/frontend-plugin-api.apifactory.md) instances, which encapsulate
|
||||
the process of instantiating an API. It is a collection of three things: the
|
||||
[`ApiRef`](../reference/core-plugin-api.apiref.md) of the API to instantiate, a
|
||||
[`ApiRef`](../reference/frontend-plugin-api.apiref.md) of the API to instantiate, a
|
||||
list of all required dependencies, and a factory function that returns a new API
|
||||
instance.
|
||||
|
||||
For example, this is the default
|
||||
[`ApiFactory`](../reference/core-plugin-api.apifactory.md) for the
|
||||
[`ErrorApi`](../reference/core-plugin-api.errorapi.md):
|
||||
[`ApiFactory`](../reference/frontend-plugin-api.apifactory.md) for the
|
||||
[`ErrorApi`](../reference/frontend-plugin-api.errorapi.md):
|
||||
|
||||
```ts
|
||||
createApiFactory({
|
||||
@@ -89,25 +89,25 @@ createApiFactory({
|
||||
});
|
||||
```
|
||||
|
||||
In this example, the [`errorApiRef`](../reference/core-plugin-api.errorapiref.md)
|
||||
In this example, the [`errorApiRef`](../reference/frontend-plugin-api.errorapiref.md)
|
||||
is our API, which encapsulates the
|
||||
[`ErrorApi`](../reference/core-plugin-api.errorapi.md) type. The
|
||||
[`alertApiRef`](../reference/core-plugin-api.alertapiref.md) is our single
|
||||
[`ErrorApi`](../reference/frontend-plugin-api.errorapi.md) type. The
|
||||
[`alertApiRef`](../reference/frontend-plugin-api.alertapiref.md) is our single
|
||||
dependency, which we give the name `alertApi`, and is then passed on to the
|
||||
factory function, which returns an implementation of the
|
||||
[`ErrorApi`](../reference/core-plugin-api.errorapi.md).
|
||||
[`ErrorApi`](../reference/frontend-plugin-api.errorapi.md).
|
||||
|
||||
The [`createApiFactory`](../reference/core-plugin-api.createapifactory.md)
|
||||
The [`createApiFactory`](../reference/frontend-plugin-api.createapifactory.md)
|
||||
function is a thin wrapper that enables TypeScript type inference. You may
|
||||
notice that there are no type annotations in the above example, and that is
|
||||
because we're able to infer all types from the
|
||||
[`ApiRef`](../reference/core-plugin-api.apiref.md)s. TypeScript will make sure
|
||||
[`ApiRef`](../reference/frontend-plugin-api.apiref.md)s. TypeScript will make sure
|
||||
that the return value of the `factory` function matches the type embedded in
|
||||
`api`'s [`ApiRef`](../reference/core-plugin-api.apiref.md), in this case the
|
||||
[`ErrorApi`](../reference/core-plugin-api.errorapi.md). It will also match the
|
||||
`api`'s [`ApiRef`](../reference/frontend-plugin-api.apiref.md), in this case the
|
||||
[`ErrorApi`](../reference/frontend-plugin-api.errorapi.md). It will also match the
|
||||
types between the `deps` and the parameters of the `factory` function, again
|
||||
using the type embedded within the
|
||||
[`ApiRef`](../reference/core-plugin-api.apiref.md)s.
|
||||
[`ApiRef`](../reference/frontend-plugin-api.apiref.md)s.
|
||||
|
||||
## Registering API Factories
|
||||
|
||||
@@ -120,8 +120,8 @@ app, and the app itself.
|
||||
Starting with the Backstage core library, it provides implementations for all of
|
||||
the core APIs. The core APIs are the ones exported by
|
||||
[`@backstage/core-plugin-api`](../reference/core-plugin-api.md), such as the
|
||||
[`errorApiRef`](../reference/core-plugin-api.errorapiref.md) and
|
||||
[`configApiRef`](../reference/core-plugin-api.configapiref.md).
|
||||
[`errorApiRef`](../reference/frontend-plugin-api.errorapiref.md) and
|
||||
[`configApiRef`](../reference/frontend-plugin-api.configapiref.md).
|
||||
|
||||
The core APIs are loaded for any app created with
|
||||
[`createApp`](../reference/app-defaults.createapp.md) from
|
||||
@@ -133,7 +133,7 @@ there is no step that needs to be taken to include these APIs in an app.
|
||||
In addition to the core APIs, plugins can define and export their own APIs.
|
||||
While doing so, they should usually also provide default implementations of their
|
||||
own APIs; for example, the `catalog` plugin exports `catalogApiRef` and also
|
||||
supplies a default [`ApiFactory`](../reference/core-plugin-api.apifactory.md) of
|
||||
supplies a default [`ApiFactory`](../reference/frontend-plugin-api.apifactory.md) of
|
||||
that API using the `CatalogClient`. There is one restriction to plugin-provided
|
||||
API Factories: plugins may not supply factories for core APIs; trying to do so
|
||||
will cause the app to refuse to start.
|
||||
@@ -227,16 +227,16 @@ const app = createApp({
|
||||
```
|
||||
|
||||
Note that the above line will cause an error if `IgnoreErrorApi` does not fully
|
||||
implement the [`ErrorApi`](../reference/core-plugin-api.errorapi.md), as it is
|
||||
implement the [`ErrorApi`](../reference/frontend-plugin-api.errorapi.md), as it is
|
||||
checked by the type embedded in the
|
||||
[`errorApiRef`](../reference/core-plugin-api.errorapiref.md) at compile time.
|
||||
[`errorApiRef`](../reference/frontend-plugin-api.errorapiref.md) at compile time.
|
||||
|
||||
## Defining custom Utility APIs
|
||||
|
||||
Plugins are free to define their own Utility APIs. Simply define the TypeScript
|
||||
interface for the API and create an
|
||||
[`ApiRef`](../reference/core-plugin-api.apiref.md) using
|
||||
[`createApiRef`](../reference/core-plugin-api.createapiref.md) exported from
|
||||
[`ApiRef`](../reference/frontend-plugin-api.apiref.md) using
|
||||
[`createApiRef`](../reference/frontend-plugin-api.createapiref.md) exported from
|
||||
[`@backstage/core-plugin-api`](../reference/core-plugin-api.md). Also, be sure to
|
||||
provide at least one implementation of the API and to declare a default factory
|
||||
for the API in [`createPlugin`](../reference/core-plugin-api.createplugin.md).
|
||||
@@ -244,16 +244,16 @@ for the API in [`createPlugin`](../reference/core-plugin-api.createplugin.md).
|
||||
Custom Utility APIs can be either public or private, which is up to the plugin to choose. Private APIs do not expose an external API surface, and it's therefore possible to make breaking changes to the API without affecting other users of the plugin. If an API is made public, however, it opens up for other plugins to make use of the API, and it also makes it possible for users for your plugin to override the API in the app. It is, however, important to maintain backward compatibility of public APIs, as you may otherwise break apps that are using your plugin.
|
||||
|
||||
To make an API public, simply export the
|
||||
[`ApiRef`](../reference/core-plugin-api.apiref.md) of the API, and any associated
|
||||
[`ApiRef`](../reference/frontend-plugin-api.apiref.md) of the API, and any associated
|
||||
types. To make an API private, just avoid exporting the
|
||||
[`ApiRef`](../reference/core-plugin-api.apiref.md), but still be sure to supply a
|
||||
[`ApiRef`](../reference/frontend-plugin-api.apiref.md), but still be sure to supply a
|
||||
default factory to [`createPlugin`](../reference/core-plugin-api.createplugin.md).
|
||||
|
||||
Private APIs are useful for plugins that want to depend on other APIs outside of
|
||||
React components, but not have to expose an entire API surface to maintain. When
|
||||
using private APIs, it is fine to use the `typeof` of an implementing class as
|
||||
the type parameter passed to
|
||||
[`createApiRef`](../reference/core-plugin-api.createapiref.md), while public APIs
|
||||
[`createApiRef`](../reference/frontend-plugin-api.createapiref.md), while public APIs
|
||||
should always define a separate TypeScript interface type.
|
||||
|
||||
Plugins may depend on APIs from other plugins, both in React components and as
|
||||
@@ -262,13 +262,13 @@ dependencies between plugins.
|
||||
|
||||
## Architecture
|
||||
|
||||
The [`ApiRef`](../reference/core-plugin-api.apiref.md) instances mentioned above
|
||||
The [`ApiRef`](../reference/frontend-plugin-api.apiref.md) instances mentioned above
|
||||
provide a point of indirection between consumers and producers of Utility APIs.
|
||||
It allows for plugins and components to depend on APIs in a type-safe way,
|
||||
without having a direct reference to a concrete implementation of the APIs. The
|
||||
Apps are also given a lot of flexibility in what implementations to provide. As
|
||||
long as they adhere to the contract established by an
|
||||
[`ApiRef`](../reference/core-plugin-api.apiref.md), they are free to choose any
|
||||
[`ApiRef`](../reference/frontend-plugin-api.apiref.md), they are free to choose any
|
||||
implementation they want.
|
||||
|
||||
The figure below shows the relationship between
|
||||
|
||||
@@ -115,7 +115,7 @@ example `getString`. These will throw an error if there is no value available.
|
||||
|
||||
## Accessing ConfigApi in Frontend Plugins
|
||||
|
||||
The [ConfigApi](../reference/core-plugin-api.configapi.md) in the frontend is a
|
||||
The [ConfigApi](../reference/frontend-plugin-api.configapi.md) in the frontend is a
|
||||
[UtilityApi](../api/utility-apis.md). It's accessible as usual via the
|
||||
`configApiRef` exported from `@backstage/core-plugin-api`:
|
||||
|
||||
|
||||
@@ -94,15 +94,15 @@ export const AwesomeUsersTable = () => {
|
||||
|
||||
This section describes the steps to wrap your API client in a [Utility API](../api/utility-apis.md), which are:
|
||||
|
||||
- use [`createApiRef`](../reference/core-plugin-api.createapiref.md) to create a
|
||||
new [`ApiRef`](../reference/core-plugin-api.apiref.md)
|
||||
- register an [`ApiFactory`](../reference/core-plugin-api.apifactory.md) with
|
||||
- use [`createApiRef`](../reference/frontend-plugin-api.createapiref.md) to create a
|
||||
new [`ApiRef`](../reference/frontend-plugin-api.apiref.md)
|
||||
- register an [`ApiFactory`](../reference/frontend-plugin-api.apifactory.md) with
|
||||
your plugin using
|
||||
[`createApiFactory`](../reference/core-plugin-api.createapifactory.md). This
|
||||
[`createApiFactory`](../reference/frontend-plugin-api.createapifactory.md). This
|
||||
will wrap your API implementation, associate your `ApiRef` with your
|
||||
implementation and tell backstage how to instantiate it
|
||||
- finally, you can use your API in your components by calling
|
||||
[`useApi`](../reference/core-plugin-api.useapi.md)
|
||||
[`useApi`](../reference/frontend-plugin-api.useapi.md)
|
||||
|
||||
### Defining the API client interface
|
||||
|
||||
@@ -187,8 +187,8 @@ export class MyAwesomeApiClient implements MyAwesomeApi {
|
||||
```
|
||||
|
||||
> Check out the docs for more information on the
|
||||
> [DiscoveryApi](../reference/core-plugin-api.discoveryapi.md) or the
|
||||
> [FetchApi](../reference/core-plugin-api.fetchapi.md)
|
||||
> [DiscoveryApi](../reference/frontend-plugin-api.discoveryapi.md) or the
|
||||
> [FetchApi](../reference/frontend-plugin-api.fetchapi.md)
|
||||
|
||||
### Bundling your ApiRef with your plugin
|
||||
|
||||
@@ -233,7 +233,7 @@ export const myCustomPlugin = createPlugin({
|
||||
### Using the API in your components
|
||||
|
||||
Now you should be able to access your API using the backstage hook
|
||||
[`useApi`](../reference/core-plugin-api.useapi.md) from within your plugin code.
|
||||
[`useApi`](../reference/frontend-plugin-api.useapi.md) from within your plugin code.
|
||||
|
||||
```ts title="plugins/my-awesome-plugin/src/components/AwesomeUsersTable.tsx"
|
||||
import { useApi } from '@backstage/core-plugin-api';
|
||||
|
||||
Reference in New Issue
Block a user