Merge branch 'master' of github.com:backstage/backstage into seant-splunk/awsS3_readTree_processor
Signed-off-by: Sean Tan <seant@splunk.com>
This commit is contained in:
Sean Tan
@@ -0,0 +1,2 @@
|
||||
# This is generated by build:api-docs in the root
|
||||
reference
|
||||
+106
-71
@@ -12,25 +12,32 @@ however always be a need for plugins to communicate outside of its boundaries,
|
||||
both with other plugins and the app itself.
|
||||
|
||||
Backstage provides two primary methods for plugins to communicate across their
|
||||
boundaries in client-side code. The first one being the `createPlugin` API and
|
||||
the registration hooks passed to the `register` method, and the second one being
|
||||
Utility APIs. While the `createPlugin` API is focused on the initialization
|
||||
plugins and the app, the Utility APIs provide ways for plugins to communicate
|
||||
during their entire life cycle.
|
||||
boundaries in client-side code. The first one being the
|
||||
[createPlugin](../reference/core-plugin-api.createplugin.md) API along with the
|
||||
extensions that it can provide, and the second one being Utility APIs. While the
|
||||
[createPlugin](../reference/core-plugin-api.createplugin.md) API is focused on
|
||||
the initialization plugins and the app, the Utility APIs provide ways for
|
||||
plugins to communicate during their entire life cycle.
|
||||
|
||||
## Consuming APIs
|
||||
|
||||
Each Utility API is tied to an `ApiRef` instance, which is a global singleton
|
||||
object without any additional state or functionality, its only purpose is to
|
||||
reference Utility APIs. `ApiRef`s are created using `createApiRef`, which is
|
||||
exported by `@backstage/core-plugin-api`. There are many
|
||||
[predefined Utility APIs](../reference/utility-apis/README.md) defined in
|
||||
`@backstage/core-plugin-api`, and they're all exported with a name of the
|
||||
pattern `*ApiRef`, for example `errorApiRef`.
|
||||
Each Utility API is tied to an [ApiRef](../reference/core-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
|
||||
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).
|
||||
|
||||
To access one of the Utility APIs inside a React component, use the `useApi`
|
||||
hook exported by `@backstage/core-plugin-api`, or the `withApis` HOC if you
|
||||
prefer class components. For example, the `ErrorApi` can be accessed like this:
|
||||
To access one of the Utility APIs inside a React component, use the
|
||||
[useApi](../reference/core-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
|
||||
components. For example, the
|
||||
[ErrorApi](../reference/core-plugin-api.errorapi.md) can be accessed like this:
|
||||
|
||||
```tsx
|
||||
import React from 'react';
|
||||
@@ -48,24 +55,31 @@ export const MyComponent = () => {
|
||||
};
|
||||
```
|
||||
|
||||
Note that there is no explicit type given for `ErrorApi`. This is because the
|
||||
`errorApiRef` has the type embedded, and `useApi` is able to infer the type.
|
||||
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
|
||||
the type.
|
||||
|
||||
Also note that consuming Utility APIs is not limited to plugins, it can be done
|
||||
from any component inside Backstage, including the ones in
|
||||
`@backstage/core-plugin-api`. The only requirement is that they are beneath the
|
||||
`AppProvider` in the react tree.
|
||||
[@backstage/core-plugin-api](../reference/core-plugin-api.md). The only
|
||||
requirement is that they are beneath the `AppProvider` in the react tree.
|
||||
|
||||
## Supplying APIs
|
||||
|
||||
### API Factories
|
||||
|
||||
APIs are registered in the form of `ApiFactories`, which encapsulate the process
|
||||
of instantiating an API. It is a collection of three things: the `ApiRef` of the
|
||||
API to instantiate, a list of all required dependencies, and a factory function
|
||||
that returns a new API instance.
|
||||
APIs are registered in the form of
|
||||
[ApiFactories](../reference/core-plugin-api.apifactory.md), 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
|
||||
list of all required dependencies, and a factory function that returns a new API
|
||||
instance.
|
||||
|
||||
For example, this is the default `ApiFactory` for the `ErrorApi`:
|
||||
For example, this is the default
|
||||
[ApiFactory](../reference/core-plugin-api.apifactory.md) for the
|
||||
[ErrorApi](../reference/core-plugin-api.errorapi.md):
|
||||
|
||||
```ts
|
||||
createApiFactory({
|
||||
@@ -79,18 +93,25 @@ createApiFactory({
|
||||
});
|
||||
```
|
||||
|
||||
In this example the `errorApiRef` is our API, which encapsulates the `ErrorApi`
|
||||
type. The `alertApiRef` 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`.
|
||||
In this example the [errorApiRef](../reference/core-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
|
||||
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).
|
||||
|
||||
The `createApiFactory` 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`s.
|
||||
TypeScript will make sure that the return value of the `factory` function
|
||||
matches the type embedded in `api`'s `ApiRef`, in this case the `ErrorApi`. It
|
||||
will also match the types between the `deps` and the parameters of the `factory`
|
||||
function, again using the type embedded within the `ApiRef`s.
|
||||
The [createApiFactory](../reference/core-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
|
||||
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
|
||||
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.
|
||||
|
||||
## Registering API Factories
|
||||
|
||||
@@ -102,24 +123,27 @@ 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`, such as the `errorApiRef` and `configApiRef`. You
|
||||
can find a full list of them [here](../reference/utility-apis/README.md).
|
||||
[@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).
|
||||
|
||||
The core APIs are loaded for any app created with `createApp` from
|
||||
`@backstage/core-plugin-api`, which means that there is no step that needs to be
|
||||
taken to include these APIs in an app.
|
||||
The core APIs are loaded for any app created with
|
||||
[createApp](../reference/core-app-api.createapp.md) from
|
||||
[@backstage/core-plugin-api](../reference/core-plugin-api.md), which means that
|
||||
there is no step that needs to be taken to include these APIs in an app.
|
||||
|
||||
### Plugin APIs
|
||||
|
||||
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` 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.
|
||||
supplies a default [ApiFactory](../reference/core-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.
|
||||
|
||||
Plugins supply their APIs through the `apis` option of `createPlugin`, for
|
||||
example:
|
||||
Plugins supply their APIs through the `apis` option of
|
||||
[createPlugin](../reference/core-plugin-api.createplugin.md), for example:
|
||||
|
||||
```ts
|
||||
export const techdocsPlugin = createPlugin({
|
||||
@@ -144,7 +168,8 @@ Lastly, the app itself is the final point where APIs can be added, and what has
|
||||
the final say in what APIs will be loaded at runtime. The app may override the
|
||||
factories for any of the core or plugin APIs, with the exception of the config,
|
||||
app theme, and identity APIs. These are static APIs that are tied into the
|
||||
`createApp` implementation, and therefore not possible to override.
|
||||
[createApp](../reference/core-app-api.createapp.md) implementation, and
|
||||
therefore not possible to override.
|
||||
|
||||
Overriding APIs is useful for apps that want to switch out behavior to tailor it
|
||||
to their environment. In some cases plugins may also export multiple
|
||||
@@ -206,16 +231,19 @@ const app = createApp({
|
||||
```
|
||||
|
||||
Note that the above line will cause an error if `IgnoreErrorApi` does not fully
|
||||
implement the `ErrorApi`, as it is checked by the type embedded in the
|
||||
`errorApiRef` at compile time.
|
||||
implement the [ErrorApi](../reference/core-plugin-api.errorapi.md), as it is
|
||||
checked by the type embedded in the
|
||||
[errorApiRef](../reference/core-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` using `createApiRef` exported from
|
||||
`@backstage/core-plugin-api`. Also be sure to provide at least one
|
||||
implementation of the API, and to declare a default factory for the API in
|
||||
`createPlugin`.
|
||||
interface for the API, and create an
|
||||
[ApiRef](../reference/core-plugin-api.apiref.md) using
|
||||
[createApiRef](../reference/core-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).
|
||||
|
||||
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
|
||||
@@ -226,15 +254,18 @@ plugin to override the API in the app. It is however important to maintain
|
||||
backwards compatibility of public APIs, as you may otherwise break apps that are
|
||||
using your plugin.
|
||||
|
||||
To make an API public, simply export the `ApiRef` of the API, and any associated
|
||||
types. To make an API private, just avoid exporting the `ApiRef`, but still be
|
||||
sure to supply a default factory to `createPlugin`.
|
||||
To make an API public, simply export the
|
||||
[ApiRef](../reference/core-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
|
||||
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`, while public APIs should always
|
||||
define a separate TypeScript interface type.
|
||||
the type parameter passed to
|
||||
[createApiRef](../reference/core-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
|
||||
dependencies to API factories. Do however be sure to not cause circular
|
||||
@@ -242,13 +273,14 @@ dependencies between plugins.
|
||||
|
||||
## Architecture
|
||||
|
||||
The `ApiRef` 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`, they are free to choose any implementation
|
||||
they want.
|
||||
The [ApiRef](../reference/core-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
|
||||
implementation they want.
|
||||
|
||||
The figure below shows the relationship between
|
||||
<span style="color: #82b366">different Apps</span>, that provide
|
||||
@@ -271,14 +303,17 @@ directly tied to React.
|
||||
The indirection provided by Utility APIs also makes it straightforward to test
|
||||
components that depend on APIs, and to provide a standard common development
|
||||
environment for plugins. A proper test wrapper with mocked API implementations
|
||||
is not yet ready, but it will be provided as a part of `@backstage/test-utils`.
|
||||
It will provide mocked variants of APIs, with additional methods for asserting a
|
||||
component's interaction with the API.
|
||||
is not yet ready, but it will be provided as a part of
|
||||
[@backstage/test-utils](../reference/test-utils.md). It will provide mocked
|
||||
variants of APIs, with additional methods for asserting a component's
|
||||
interaction with the API.
|
||||
|
||||
The common development environment for plugins is included in
|
||||
`@backstage/dev-utils`, where the exported `createDevApp` function creates an
|
||||
[@backstage/dev-utils](../reference/dev-utils.md), where the exported
|
||||
[createDevApp](../reference/dev-utils.createdevapp.md) function creates an
|
||||
application with implementations for all core APIs already present. Contrary to
|
||||
the method for wiring up Utility API implementations in an app created with
|
||||
`createApp`, `createDevApp` uses automatic dependency injection. This is to make
|
||||
it possible to replace any API implementation, and having that be reflected in
|
||||
dependents of that API.
|
||||
[createApp](../reference/core-app-api.createapp.md),
|
||||
[createDevApp](../reference/dev-utils.createdevapp.md) uses automatic dependency
|
||||
injection. This is to make it possible to replace any API implementation, and
|
||||
having that be reflected in dependents of that API.
|
||||
|
||||
+2
-3
@@ -60,9 +60,8 @@ small update to show this provider as a login option. The `SignInPage` component
|
||||
handles this, and takes either a `provider` or `providers` (array) prop of
|
||||
`SignInProviderConfig` definitions.
|
||||
|
||||
These reference the [ApiRef](../reference/utility-apis/README.md) exported by
|
||||
the provider. Again, an example using GitHub that can be adapted to any of the
|
||||
built-in providers:
|
||||
These reference the `ApiRef` exported by the provider. Again, an example using
|
||||
GitHub that can be adapted to any of the built-in providers:
|
||||
|
||||
```diff
|
||||
# packages/app/src/App.tsx
|
||||
|
||||
@@ -28,7 +28,8 @@ OAuth helps in that regard.
|
||||
The method with which frontend plugins request access to third party services is
|
||||
through [Utility APIs](../api/utility-apis.md) for each service provider. For a
|
||||
full list of providers, see the
|
||||
[Utility API References](../reference/utility-apis/README.md).
|
||||
[@backstage/core-plugin-api](../reference/core-plugin-api.md#variables)
|
||||
reference.
|
||||
|
||||
### Identity - WIP
|
||||
|
||||
|
||||
+12
-3
@@ -7,7 +7,7 @@ description: Documentation on Reading Backstage Configuration
|
||||
## Config API
|
||||
|
||||
There's a common configuration API for by both frontend and backend plugins. An
|
||||
API reference can be found [here](../reference/utility-apis/Config.md).
|
||||
API reference can be found [here](../reference/config.config.md).
|
||||
|
||||
The configuration API is tailored towards failing fast in case of missing or bad
|
||||
config. That's because configuration errors can always be considered programming
|
||||
@@ -110,9 +110,18 @@ example `getString`. These will throw an error if there is no value available.
|
||||
|
||||
## Accessing ConfigApi in Frontend Plugins
|
||||
|
||||
The [ConfigApi](../reference/utility-apis/Config.md) in the frontend is a
|
||||
The [ConfigApi](../reference/core-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`.
|
||||
`configApiRef` exported from `@backstage/core-plugin-api`:
|
||||
|
||||
```
|
||||
import { useApi, configApiRef } from '@backstage/core-plugin-api';
|
||||
...
|
||||
const MyReactComponent = (...) => {
|
||||
const config = useApi(configApiRef);
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
Depending on the config api in another API is slightly different though, as the
|
||||
`ConfigApi` implementation is supplied via the App itself and not instantiated
|
||||
|
||||
@@ -113,6 +113,9 @@ browser at `http://localhost:7000`
|
||||
|
||||
## Multi-stage Build
|
||||
|
||||
> NOTE: The `.dockerignore` is different in this setup, read on for more
|
||||
> details.
|
||||
|
||||
This section describes how to set up a multi-stage Docker build that builds the
|
||||
entire project within Docker. This is typically slower than a host build, but is
|
||||
sometimes desired because Docker in Docker is not available in the build
|
||||
@@ -137,6 +140,7 @@ WORKDIR /app
|
||||
COPY package.json yarn.lock ./
|
||||
|
||||
COPY packages packages
|
||||
# Comment this out if you don't have any internal plugins
|
||||
COPY plugins plugins
|
||||
|
||||
RUN find packages \! -name "package.json" -mindepth 2 -maxdepth 2 -exec rm -rf {} \+
|
||||
@@ -182,8 +186,9 @@ end up being properly installed.
|
||||
|
||||
To speed up the build when not running in a fresh clone of the repo you should
|
||||
set up a `.dockerignore`. This one is different than the host build one, because
|
||||
we want to have access to the source code of all packages for the build, but can
|
||||
ignore any existing build output or dependencies:
|
||||
we want to have access to the source code of all packages for the build. We can
|
||||
however ignore any existing build output or dependencies on the host. For our
|
||||
new `.dockerignore`, replace the contents of your existing one with this:
|
||||
|
||||
```text
|
||||
node_modules
|
||||
|
||||
@@ -393,3 +393,39 @@ of interest to you, you might consider contacting the maintainers on Discord or
|
||||
my making a GitHub issue describing your use case.
|
||||
[This issue](https://github.com/backstage/backstage/issues/2292) also contains
|
||||
more context.
|
||||
|
||||
## Referencing different environments with the model
|
||||
|
||||
Example intent:
|
||||
|
||||
> "I have multiple versions of my API deployed in different environments so I
|
||||
> want to have `mytool-dev` and `mytool-prod` as different entities."
|
||||
|
||||
While it's possible to have different versions of the same thing represented as
|
||||
separate entities, it's something we generally recommend against. We believe
|
||||
that a developer should be able to just find for example one `Component`
|
||||
representing a service, and to be able to see the different code versions that
|
||||
are deployed throughout your stack within its view. This reasoning works
|
||||
similarly for other kinds as well, such as `API`.
|
||||
|
||||
That being said - sometimes the differences between versions are so large, that
|
||||
they represent what is for all intents and purposes an entirely new entity as
|
||||
seen from the consumer's point of view. This can happen for example for
|
||||
different _significant_ major versions of an API, and in particular if the two
|
||||
major versions coexist in the ecosystem for some time. In those cases, it can be
|
||||
motivated to have one `my-api-v2` and one `my-api-v3` named entity. This matches
|
||||
the end user's expectations when searching for the API, and matches the desire
|
||||
to maybe have separate documentation for the two and similar. But use this
|
||||
sparingly - only do it if the extra modelling burden is outweighed by any
|
||||
potential better clarity for users.
|
||||
|
||||
When writing your custom plugins, we encourage designing them such that they can
|
||||
show all the different variations through environments etc under one canonical
|
||||
reference to your software in the catalog. For example for a continuous
|
||||
deployment plugin, a user is likely to be greatly helped by being able to see
|
||||
the entity's versions deployed in all different environments next to each other
|
||||
in one view. That is also where they might be offered the ability to promote
|
||||
from one environment to the other, do rollbacks, see their relative performance
|
||||
metrics, and similar. This coherency and collection of tooling in one place is
|
||||
where something like Backstage can offer the most value and effectiveness of
|
||||
use. Splitting your entities apart into small islands makes this harder.
|
||||
|
||||
@@ -183,6 +183,64 @@ The stitching is currently a fixed process, that cannot be modified or extended.
|
||||
This means that any modifications you want to make on the final result, has to
|
||||
happen during ingestion or processing.
|
||||
|
||||
## Deletion
|
||||
## Errors
|
||||
|
||||
> TODO
|
||||
> TODO: Describe how errors are exposed through entities
|
||||
|
||||
## Orphaning
|
||||
|
||||
As mentioned earlier, entities internally form a graph. The edges go from
|
||||
processed parent entities, to child entities emitted while processing the
|
||||
parent.
|
||||
|
||||
The processing loop runs continuously, so these edges are reconsidered over
|
||||
time. If processing a parent entity no longer emits a given child entity, then
|
||||
that former edge is severed. If that child has no other edges pointing at it
|
||||
either, it becomes _orphaned_. The end result is as follows:
|
||||
|
||||
- The stitching process injects a `backstage.io/orphan: 'true'` annotation on
|
||||
the child entity.
|
||||
- The child entity is _not_ removed from the catalog, but stays around until
|
||||
explicitly deleted via the catalog API, or "reclaimed" by the original parent
|
||||
or another parent starting to reference it.
|
||||
- The catalog page in Backstage for the child entity detects the new annotation
|
||||
and informs users about the orphan status.
|
||||
|
||||
Orphaning can occur in several different scenarios. One common cause is that the
|
||||
end user edited a corresponding catalog catalog-info YAML file removing the
|
||||
entity's entry. In the case of a `Location` parent entity, orphaning can happen
|
||||
if removing the target line pointing to the file containing the child entity.
|
||||
Another common cause is large batch processors such as the ones that crawl
|
||||
through remote systems looking for entities, no longer finding something that it
|
||||
used to find before. Maybe the data was moved, or deleted, in the remote system.
|
||||
So for example when a person leaves the company an LDAP org discovery processor
|
||||
might leave an orphaned `User` entity behind. Note that this only applies to
|
||||
processors - ingestion that happens using entity providers work differently,
|
||||
described below.
|
||||
|
||||
> Note that removing a file, or accidentally corrupting a file so that it cannot
|
||||
> be read successfully, does _not_ lead to orphaning. Hard errors, including the
|
||||
> inability to find or read a distinct remote, are marked as such on the entity
|
||||
> to inform the owner that something is wrong. But processing and other
|
||||
> behaviors continue as usual.
|
||||
|
||||
The reason that the orphaning mechanism exists instead of having an eager
|
||||
deletion triggered, is safety. Scenarios like these can happen purely by
|
||||
accident, due to the asynchronous nature of the system and the fallible nature
|
||||
of humans. In particular when external systems start consuming and relying on
|
||||
the catalog, there could be substantial consequences to suddenly dropping
|
||||
entities without explicit owner consent. The catalog therefore takes the stance
|
||||
that entities that often were added by direct user action should also be deleted
|
||||
only by direct user action.
|
||||
|
||||
It is possible to use the catalog API to build automated "reaper" systems that
|
||||
finally delete entities that are orphaned. This is however not something that's
|
||||
provided out of the box.
|
||||
|
||||
## Implicit Deletion
|
||||
|
||||
> TODO: Describe the process of entity providers eagerly deleting entities
|
||||
|
||||
## Explicit Deletion
|
||||
|
||||
> TODO: Describe direct deletion via the catalog API
|
||||
|
||||
@@ -147,11 +147,6 @@ are separated out into their own folder, see further down.
|
||||
Helps you setup a plugin for isolated development so that it can be served
|
||||
separately.
|
||||
|
||||
- [`docgen/`](https://github.com/backstage/backstage/tree/master/packages/docgen) -
|
||||
Uses the
|
||||
[TypeScript Compiler API](https://github.com/microsoft/TypeScript/wiki/Using-the-Compiler-API)
|
||||
to read out definitions and generate documentation for it.
|
||||
|
||||
- [`e2e-test/`](https://github.com/backstage/backstage/tree/master/packages/e2e-test) -
|
||||
Another CLI that can be run to try out what would happen if you build all the
|
||||
packages, publish them, create a new app, and then run them. CI uses this for
|
||||
|
||||
@@ -145,12 +145,6 @@ Provides utilities for developing plugins in isolation.
|
||||
|
||||
Stability: `0`. This package is largely broken and needs updates.
|
||||
|
||||
### `docgen` [GitHub](https://github.com/backstage/backstage/tree/master/packages/docgen/)
|
||||
|
||||
Internal CLI utility for generating API Documentation.
|
||||
|
||||
Stability: `N/A`
|
||||
|
||||
### `e2e-test` [GitHub](https://github.com/backstage/backstage/tree/master/packages/e2e-test/)
|
||||
|
||||
Internal CLI utility for running e2e tests.
|
||||
|
||||
@@ -82,8 +82,8 @@ export const ExamplePage = examplePlugin.provide(
|
||||
|
||||
This is where the plugin is created and where it creates and exports extensions
|
||||
that can be imported and used the app. See reference docs for
|
||||
[createPlugin](../reference/createPlugin.md) or introduction to the new
|
||||
[Composability System](./composability.md).
|
||||
[createPlugin](../reference/core-plugin-api.createplugin.md) or introduction to
|
||||
the new [Composability System](./composability.md).
|
||||
|
||||
## Components
|
||||
|
||||
|
||||
@@ -1,44 +0,0 @@
|
||||
---
|
||||
id: createPlugin-feature-flags
|
||||
title: createPlugin - feature flags
|
||||
description: Documentation on createPlugin - feature flags
|
||||
---
|
||||
|
||||
The `featureFlags` object passed to the `register` function makes it possible
|
||||
for plugins to register Feature Flags in Backstage for users to opt into. You
|
||||
can use this to split out logic in your code for manual A/B testing, etc.
|
||||
|
||||
Here's a code sample:
|
||||
|
||||
```typescript
|
||||
import { createPlugin } from '@backstage/core-plugin-api';
|
||||
|
||||
export default createPlugin({
|
||||
id: 'plugin-name',
|
||||
register({ featureFlags }) {
|
||||
featureFlags.register('enable-example-feature');
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
## Using with useApi
|
||||
|
||||
To inspect the state of a feature flag inside your plugin, you can use the
|
||||
`FeatureFlagsApi`, accessed via the `featureFlagsApiRef`. For example:
|
||||
|
||||
```tsx
|
||||
import React from 'react';
|
||||
import { Button } from '@material-ui/core';
|
||||
import { featureFlagsApiRef, useApi } from '@backstage/core-plugin-api';
|
||||
|
||||
const ExamplePage = () => {
|
||||
const featureFlags = useApi(featureFlagsApiRef);
|
||||
|
||||
return (
|
||||
<div>
|
||||
<MyPluginWidget>
|
||||
{ featureFlags.isActive('enable-example-feature') && <ExperimentalPluginWidget> }
|
||||
</div>
|
||||
);
|
||||
};
|
||||
```
|
||||
@@ -1,41 +0,0 @@
|
||||
---
|
||||
id: createPlugin
|
||||
title: createPlugin
|
||||
description: Documentation on createPlugin
|
||||
---
|
||||
|
||||
Takes a plugin config as an argument and returns a new plugin.
|
||||
|
||||
## Plugin Config
|
||||
|
||||
```typescript
|
||||
function createPlugin(config: PluginConfig): BackstagePlugin;
|
||||
|
||||
type PluginConfig = {
|
||||
id: string;
|
||||
register?(hooks: PluginHooks): void;
|
||||
};
|
||||
|
||||
type PluginHooks = {
|
||||
featureFlags: FeatureFlagsHooks;
|
||||
};
|
||||
```
|
||||
|
||||
- [Read more about feature flags here](createPlugin-feature-flags.md)
|
||||
|
||||
## Example Uses
|
||||
|
||||
### Creating a basic plugin
|
||||
|
||||
Showcasing adding a feature flag.
|
||||
|
||||
```jsx
|
||||
import { createPlugin } from '@backstage/core-plugin-api';
|
||||
|
||||
export default createPlugin({
|
||||
id: 'new-plugin',
|
||||
register({ router, featureFlags }) {
|
||||
featureFlags.register('enable-example-component');
|
||||
},
|
||||
});
|
||||
```
|
||||
@@ -1,114 +0,0 @@
|
||||
# AlertApi
|
||||
|
||||
The AlertApi type is defined at
|
||||
[packages/core-api/src/apis/definitions/AlertApi.ts:29](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/AlertApi.ts#L29).
|
||||
|
||||
The following Utility API implements this type: [alertApiRef](./README.md#alert)
|
||||
|
||||
## Members
|
||||
|
||||
### post()
|
||||
|
||||
Post an alert for handling by the application.
|
||||
|
||||
<pre>
|
||||
post(alert: <a href="#alertmessage">AlertMessage</a>): void
|
||||
</pre>
|
||||
|
||||
### alert\$()
|
||||
|
||||
Observe alerts posted by other parts of the application.
|
||||
|
||||
<pre>
|
||||
alert$(): <a href="#observable">Observable</a><<a href="#alertmessage">AlertMessage</a>>
|
||||
</pre>
|
||||
|
||||
## Supporting types
|
||||
|
||||
These types are part of the API declaration, but may not be unique to this API.
|
||||
|
||||
### AlertMessage
|
||||
|
||||
<pre>
|
||||
export type AlertMessage = {
|
||||
message: string;
|
||||
// Severity will default to success since that is what material ui defaults the value to.
|
||||
severity?: 'success' | 'info' | 'warning' | 'error';
|
||||
}
|
||||
</pre>
|
||||
|
||||
Defined at
|
||||
[packages/core-api/src/apis/definitions/AlertApi.ts:19](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/AlertApi.ts#L19).
|
||||
|
||||
Referenced by: [post](#post), [alert\$](#alert).
|
||||
|
||||
### Observable
|
||||
|
||||
Observable sequence of values and errors, see TC39.
|
||||
|
||||
https://github.com/tc39/proposal-observable
|
||||
|
||||
This is used as a common return type for observable values and can be created
|
||||
using many different observable implementations, such as zen-observable or
|
||||
RxJS 5.
|
||||
|
||||
<pre>
|
||||
export type Observable<T> = {
|
||||
/**
|
||||
* Subscribes to this observable to start receiving new values.
|
||||
*/
|
||||
subscribe(observer: <a href="#observer">Observer</a><T>): <a href="#subscription">Subscription</a>;
|
||||
subscribe(
|
||||
onNext: (value: T) => void,
|
||||
onError?: (error: Error) => void,
|
||||
onComplete?: () => void,
|
||||
): <a href="#subscription">Subscription</a>;
|
||||
}
|
||||
</pre>
|
||||
|
||||
Defined at
|
||||
[packages/core-api/src/types.ts:53](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/types.ts#L53).
|
||||
|
||||
Referenced by: [alert\$](#alert).
|
||||
|
||||
### Observer
|
||||
|
||||
This file contains non-react related core types used throughout Backstage.
|
||||
|
||||
Observer interface for consuming an Observer, see TC39.
|
||||
|
||||
<pre>
|
||||
export type Observer<T> = {
|
||||
next?(value: T): void;
|
||||
error?(error: Error): void;
|
||||
complete?(): void;
|
||||
}
|
||||
</pre>
|
||||
|
||||
Defined at
|
||||
[packages/core-api/src/types.ts:24](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/types.ts#L24).
|
||||
|
||||
Referenced by: [Observable](#observable).
|
||||
|
||||
### Subscription
|
||||
|
||||
Subscription returned when subscribing to an Observable, see TC39.
|
||||
|
||||
<pre>
|
||||
export type Subscription = {
|
||||
/**
|
||||
* Cancels the subscription
|
||||
*/
|
||||
unsubscribe(): void;
|
||||
|
||||
/**
|
||||
* Value indicating whether the subscription is closed.
|
||||
*/
|
||||
readonly closed: Boolean;
|
||||
}
|
||||
</pre>
|
||||
|
||||
Defined at
|
||||
[packages/core-api/src/types.ts:33](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/types.ts#L33).
|
||||
|
||||
Referenced by: [Observable](#observable).
|
||||
@@ -1,271 +0,0 @@
|
||||
# AppThemeApi
|
||||
|
||||
The AppThemeApi type is defined at
|
||||
[packages/core-api/src/apis/definitions/AppThemeApi.ts:56](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/AppThemeApi.ts#L56).
|
||||
|
||||
The following Utility API implements this type:
|
||||
[appThemeApiRef](./README.md#apptheme)
|
||||
|
||||
## Members
|
||||
|
||||
### getInstalledThemes()
|
||||
|
||||
Get a list of available themes.
|
||||
|
||||
<pre>
|
||||
getInstalledThemes(): <a href="#apptheme">AppTheme</a>[]
|
||||
</pre>
|
||||
|
||||
### activeThemeId\$()
|
||||
|
||||
Observe the currently selected theme. A value of undefined means no specific
|
||||
theme has been selected.
|
||||
|
||||
<pre>
|
||||
activeThemeId$(): <a href="#observable">Observable</a><string | undefined>
|
||||
</pre>
|
||||
|
||||
### getActiveThemeId()
|
||||
|
||||
Get the current theme ID. Returns undefined if no specific theme is selected.
|
||||
|
||||
<pre>
|
||||
getActiveThemeId(): string | undefined
|
||||
</pre>
|
||||
|
||||
### setActiveThemeId()
|
||||
|
||||
Set a specific theme to use in the app, overriding the default theme selection.
|
||||
|
||||
Clear the selection by passing in undefined.
|
||||
|
||||
<pre>
|
||||
setActiveThemeId(themeId?: string): void
|
||||
</pre>
|
||||
|
||||
## Supporting types
|
||||
|
||||
These types are part of the API declaration, but may not be unique to this API.
|
||||
|
||||
### AppTheme
|
||||
|
||||
Describes a theme provided by the app.
|
||||
|
||||
<pre>
|
||||
export type AppTheme = {
|
||||
/**
|
||||
* ID used to remember theme selections.
|
||||
*/
|
||||
id: string;
|
||||
|
||||
/**
|
||||
* Title of the theme
|
||||
*/
|
||||
title: string;
|
||||
|
||||
/**
|
||||
* Theme variant
|
||||
*/
|
||||
variant: 'light' | 'dark';
|
||||
|
||||
/**
|
||||
* The specialized MaterialUI theme instance.
|
||||
*/
|
||||
theme: <a href="#backstagetheme">BackstageTheme</a>;
|
||||
|
||||
/**
|
||||
* An Icon for the theme mode setting.
|
||||
*/
|
||||
icon?: React.ReactElement<SvgIconProps>;
|
||||
}
|
||||
</pre>
|
||||
|
||||
Defined at
|
||||
[packages/core-api/src/apis/definitions/AppThemeApi.ts:25](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/AppThemeApi.ts#L25).
|
||||
|
||||
Referenced by: [getInstalledThemes](#getinstalledthemes).
|
||||
|
||||
### BackstagePalette
|
||||
|
||||
<pre>
|
||||
export type BackstagePalette = Palette & <a href="#paletteadditions">PaletteAdditions</a>
|
||||
</pre>
|
||||
|
||||
Defined at
|
||||
[packages/theme/src/types.ts:74](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/theme/src/types.ts#L74).
|
||||
|
||||
Referenced by: [BackstageTheme](#backstagetheme).
|
||||
|
||||
### BackstageTheme
|
||||
|
||||
<pre>
|
||||
export interface BackstageTheme extends Theme {
|
||||
palette: <a href="#backstagepalette">BackstagePalette</a>;
|
||||
page: <a href="#pagetheme">PageTheme</a>;
|
||||
getPageTheme: ({ themeId }: <a href="#pagethemeselector">PageThemeSelector</a>) => <a href="#pagetheme">PageTheme</a>;
|
||||
}
|
||||
</pre>
|
||||
|
||||
Defined at
|
||||
[packages/theme/src/types.ts:81](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/theme/src/types.ts#L81).
|
||||
|
||||
Referenced by: [AppTheme](#apptheme).
|
||||
|
||||
### Observable
|
||||
|
||||
Observable sequence of values and errors, see TC39.
|
||||
|
||||
https://github.com/tc39/proposal-observable
|
||||
|
||||
This is used as a common return type for observable values and can be created
|
||||
using many different observable implementations, such as zen-observable or
|
||||
RxJS 5.
|
||||
|
||||
<pre>
|
||||
export type Observable<T> = {
|
||||
/**
|
||||
* Subscribes to this observable to start receiving new values.
|
||||
*/
|
||||
subscribe(observer: <a href="#observer">Observer</a><T>): <a href="#subscription">Subscription</a>;
|
||||
subscribe(
|
||||
onNext: (value: T) => void,
|
||||
onError?: (error: Error) => void,
|
||||
onComplete?: () => void,
|
||||
): <a href="#subscription">Subscription</a>;
|
||||
}
|
||||
</pre>
|
||||
|
||||
Defined at
|
||||
[packages/core-api/src/types.ts:53](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/types.ts#L53).
|
||||
|
||||
Referenced by: [activeThemeId\$](#activethemeid).
|
||||
|
||||
### Observer
|
||||
|
||||
This file contains non-react related core types used throughout Backstage.
|
||||
|
||||
Observer interface for consuming an Observer, see TC39.
|
||||
|
||||
<pre>
|
||||
export type Observer<T> = {
|
||||
next?(value: T): void;
|
||||
error?(error: Error): void;
|
||||
complete?(): void;
|
||||
}
|
||||
</pre>
|
||||
|
||||
Defined at
|
||||
[packages/core-api/src/types.ts:24](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/types.ts#L24).
|
||||
|
||||
Referenced by: [Observable](#observable).
|
||||
|
||||
### PageTheme
|
||||
|
||||
<pre>
|
||||
export type PageTheme = {
|
||||
colors: string[];
|
||||
shape: string;
|
||||
backgroundImage: string;
|
||||
}
|
||||
</pre>
|
||||
|
||||
Defined at
|
||||
[packages/theme/src/types.ts:103](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/theme/src/types.ts#L103).
|
||||
|
||||
Referenced by: [BackstageTheme](#backstagetheme).
|
||||
|
||||
### PageThemeSelector
|
||||
|
||||
<pre>
|
||||
export type PageThemeSelector = {
|
||||
themeId: string;
|
||||
}
|
||||
</pre>
|
||||
|
||||
Defined at
|
||||
[packages/theme/src/types.ts:77](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/theme/src/types.ts#L77).
|
||||
|
||||
Referenced by: [BackstageTheme](#backstagetheme).
|
||||
|
||||
### PaletteAdditions
|
||||
|
||||
<pre>
|
||||
type PaletteAdditions = {
|
||||
status: {
|
||||
ok: string;
|
||||
warning: string;
|
||||
error: string;
|
||||
pending: string;
|
||||
running: string;
|
||||
aborted: string;
|
||||
};
|
||||
border: string;
|
||||
textContrast: string;
|
||||
textVerySubtle: string;
|
||||
textSubtle: string;
|
||||
highlight: string;
|
||||
errorBackground: string;
|
||||
warningBackground: string;
|
||||
infoBackground: string;
|
||||
errorText: string;
|
||||
infoText: string;
|
||||
warningText: string;
|
||||
linkHover: string;
|
||||
link: string;
|
||||
gold: string;
|
||||
navigation: {
|
||||
background: string;
|
||||
indicator: string;
|
||||
color: string;
|
||||
selectedColor: string;
|
||||
};
|
||||
tabbar: {
|
||||
indicator: string;
|
||||
};
|
||||
bursts: {
|
||||
fontColor: string;
|
||||
slackChannelText: string;
|
||||
backgroundColor: {
|
||||
default: string;
|
||||
};
|
||||
};
|
||||
pinSidebarButton: {
|
||||
icon: string;
|
||||
background: string;
|
||||
};
|
||||
banner: {
|
||||
info: string;
|
||||
error: string;
|
||||
text: string;
|
||||
link: string;
|
||||
};
|
||||
}
|
||||
</pre>
|
||||
|
||||
Defined at
|
||||
[packages/theme/src/types.ts:23](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/theme/src/types.ts#L23).
|
||||
|
||||
Referenced by: [BackstagePalette](#backstagepalette).
|
||||
|
||||
### Subscription
|
||||
|
||||
Subscription returned when subscribing to an Observable, see TC39.
|
||||
|
||||
<pre>
|
||||
export type Subscription = {
|
||||
/**
|
||||
* Cancels the subscription
|
||||
*/
|
||||
unsubscribe(): void;
|
||||
|
||||
/**
|
||||
* Value indicating whether the subscription is closed.
|
||||
*/
|
||||
readonly closed: Boolean;
|
||||
}
|
||||
</pre>
|
||||
|
||||
Defined at
|
||||
[packages/core-api/src/types.ts:33](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/types.ts#L33).
|
||||
|
||||
Referenced by: [Observable](#observable).
|
||||
@@ -1,100 +0,0 @@
|
||||
# BackstageIdentityApi
|
||||
|
||||
The BackstageIdentityApi type is defined at
|
||||
[packages/core-api/src/apis/definitions/auth.ts:134](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/auth.ts#L134).
|
||||
|
||||
The following Utility APIs implement this type:
|
||||
|
||||
- [auth0AuthApiRef](./README.md#auth0auth)
|
||||
|
||||
- [githubAuthApiRef](./README.md#githubauth)
|
||||
|
||||
- [gitlabAuthApiRef](./README.md#gitlabauth)
|
||||
|
||||
- [googleAuthApiRef](./README.md#googleauth)
|
||||
|
||||
- [microsoftAuthApiRef](./README.md#microsoftauth)
|
||||
|
||||
- [oauth2ApiRef](./README.md#oauth2)
|
||||
|
||||
- [oidcAuthApiRef](./README.md#oidcauth)
|
||||
|
||||
- [oktaAuthApiRef](./README.md#oktaauth)
|
||||
|
||||
- [oneloginAuthApiRef](./README.md#oneloginauth)
|
||||
|
||||
- [samlAuthApiRef](./README.md#samlauth)
|
||||
|
||||
## Members
|
||||
|
||||
### getBackstageIdentity()
|
||||
|
||||
Get the user's identity within Backstage. This should normally not be called
|
||||
directly, use the @IdentityApi instead.
|
||||
|
||||
If the optional flag is not set, a session is guaranteed to be returned, while
|
||||
if the optional flag is set, the session may be undefined. See
|
||||
@AuthRequestOptions for more details.
|
||||
|
||||
<pre>
|
||||
getBackstageIdentity(
|
||||
options?: <a href="#authrequestoptions">AuthRequestOptions</a>,
|
||||
): Promise<<a href="#backstageidentity">BackstageIdentity</a> | undefined>
|
||||
</pre>
|
||||
|
||||
## Supporting types
|
||||
|
||||
These types are part of the API declaration, but may not be unique to this API.
|
||||
|
||||
### AuthRequestOptions
|
||||
|
||||
<pre>
|
||||
export type AuthRequestOptions = {
|
||||
/**
|
||||
* If this is set to true, the user will not be prompted to log in,
|
||||
* and an empty response will be returned if there is no existing session.
|
||||
*
|
||||
* This can be used to perform a check whether the user is logged in, or if you don't
|
||||
* want to force a user to be logged in, but provide functionality if they already are.
|
||||
*
|
||||
* @default false
|
||||
*/
|
||||
optional?: boolean;
|
||||
|
||||
/**
|
||||
* If this is set to true, the request will bypass the regular oauth login modal
|
||||
* and open the login popup directly.
|
||||
*
|
||||
* The method must be called synchronously from a user action for this to work in all browsers.
|
||||
*
|
||||
* @default false
|
||||
*/
|
||||
instantPopup?: boolean;
|
||||
}
|
||||
</pre>
|
||||
|
||||
Defined at
|
||||
[packages/core-api/src/apis/definitions/auth.ts:40](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/auth.ts#L40).
|
||||
|
||||
Referenced by: [getBackstageIdentity](#getbackstageidentity).
|
||||
|
||||
### BackstageIdentity
|
||||
|
||||
<pre>
|
||||
export type BackstageIdentity = {
|
||||
/**
|
||||
* The backstage user ID.
|
||||
*/
|
||||
id: string;
|
||||
|
||||
/**
|
||||
* An ID token that can be used to authenticate the user within Backstage.
|
||||
*/
|
||||
idToken: string;
|
||||
}
|
||||
</pre>
|
||||
|
||||
Defined at
|
||||
[packages/core-api/src/apis/definitions/auth.ts:147](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/auth.ts#L147).
|
||||
|
||||
Referenced by: [getBackstageIdentity](#getbackstageidentity).
|
||||
@@ -1,187 +0,0 @@
|
||||
# Config
|
||||
|
||||
The Config type is defined at
|
||||
[packages/config/src/types.ts:32](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/config/src/types.ts#L32).
|
||||
|
||||
The following Utility API implements this type:
|
||||
[configApiRef](./README.md#config)
|
||||
|
||||
## Members
|
||||
|
||||
### has()
|
||||
|
||||
<pre>
|
||||
has(key: string): boolean
|
||||
</pre>
|
||||
|
||||
### keys()
|
||||
|
||||
<pre>
|
||||
keys(): string[]
|
||||
</pre>
|
||||
|
||||
### get()
|
||||
|
||||
<pre>
|
||||
get(key?: string): <a href="#jsonvalue">JsonValue</a>
|
||||
</pre>
|
||||
|
||||
### getOptional()
|
||||
|
||||
<pre>
|
||||
getOptional(key?: string): <a href="#jsonvalue">JsonValue</a> | undefined
|
||||
</pre>
|
||||
|
||||
### getConfig()
|
||||
|
||||
<pre>
|
||||
getConfig(key: string): <a href="#config">Config</a>
|
||||
</pre>
|
||||
|
||||
### getOptionalConfig()
|
||||
|
||||
<pre>
|
||||
getOptionalConfig(key: string): <a href="#config">Config</a> | undefined
|
||||
</pre>
|
||||
|
||||
### getConfigArray()
|
||||
|
||||
<pre>
|
||||
getConfigArray(key: string): <a href="#config">Config</a>[]
|
||||
</pre>
|
||||
|
||||
### getOptionalConfigArray()
|
||||
|
||||
<pre>
|
||||
getOptionalConfigArray(key: string): <a href="#config">Config</a>[] | undefined
|
||||
</pre>
|
||||
|
||||
### getNumber()
|
||||
|
||||
<pre>
|
||||
getNumber(key: string): number
|
||||
</pre>
|
||||
|
||||
### getOptionalNumber()
|
||||
|
||||
<pre>
|
||||
getOptionalNumber(key: string): number | undefined
|
||||
</pre>
|
||||
|
||||
### getBoolean()
|
||||
|
||||
<pre>
|
||||
getBoolean(key: string): boolean
|
||||
</pre>
|
||||
|
||||
### getOptionalBoolean()
|
||||
|
||||
<pre>
|
||||
getOptionalBoolean(key: string): boolean | undefined
|
||||
</pre>
|
||||
|
||||
### getString()
|
||||
|
||||
<pre>
|
||||
getString(key: string): string
|
||||
</pre>
|
||||
|
||||
### getOptionalString()
|
||||
|
||||
<pre>
|
||||
getOptionalString(key: string): string | undefined
|
||||
</pre>
|
||||
|
||||
### getStringArray()
|
||||
|
||||
<pre>
|
||||
getStringArray(key: string): string[]
|
||||
</pre>
|
||||
|
||||
### getOptionalStringArray()
|
||||
|
||||
<pre>
|
||||
getOptionalStringArray(key: string): string[] | undefined
|
||||
</pre>
|
||||
|
||||
## Supporting types
|
||||
|
||||
These types are part of the API declaration, but may not be unique to this API.
|
||||
|
||||
### Config
|
||||
|
||||
<pre>
|
||||
export type Config = {
|
||||
has(key: string): boolean;
|
||||
|
||||
keys(): string[];
|
||||
|
||||
get(key?: string): <a href="#jsonvalue">JsonValue</a>;
|
||||
getOptional(key?: string): <a href="#jsonvalue">JsonValue</a> | undefined;
|
||||
|
||||
getConfig(key: string): Config;
|
||||
getOptionalConfig(key: string): <a href="#config">Config</a> | undefined;
|
||||
|
||||
getConfigArray(key: string): <a href="#config">Config</a>[];
|
||||
getOptionalConfigArray(key: string): <a href="#config">Config</a>[] | undefined;
|
||||
|
||||
getNumber(key: string): number;
|
||||
getOptionalNumber(key: string): number | undefined;
|
||||
|
||||
getBoolean(key: string): boolean;
|
||||
getOptionalBoolean(key: string): boolean | undefined;
|
||||
|
||||
getString(key: string): string;
|
||||
getOptionalString(key: string): string | undefined;
|
||||
|
||||
getStringArray(key: string): string[];
|
||||
getOptionalStringArray(key: string): string[] | undefined;
|
||||
}
|
||||
</pre>
|
||||
|
||||
Defined at
|
||||
[packages/config/src/types.ts:32](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/config/src/types.ts#L32).
|
||||
|
||||
Referenced by: [getConfig](#getconfig), [getOptionalConfig](#getoptionalconfig),
|
||||
[getConfigArray](#getconfigarray),
|
||||
[getOptionalConfigArray](#getoptionalconfigarray), [Config](#config).
|
||||
|
||||
### JsonArray
|
||||
|
||||
<pre>
|
||||
export type JsonArray = <a href="#jsonvalue">JsonValue</a>[]
|
||||
</pre>
|
||||
|
||||
Defined at
|
||||
[packages/config/src/types.ts:18](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/config/src/types.ts#L18).
|
||||
|
||||
Referenced by: [JsonValue](#jsonvalue).
|
||||
|
||||
### JsonObject
|
||||
|
||||
<pre>
|
||||
export type JsonObject = { [key in string]?: <a href="#jsonvalue">JsonValue</a> }
|
||||
</pre>
|
||||
|
||||
Defined at
|
||||
[packages/config/src/types.ts:17](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/config/src/types.ts#L17).
|
||||
|
||||
Referenced by: [JsonValue](#jsonvalue).
|
||||
|
||||
### JsonValue
|
||||
|
||||
<pre>
|
||||
export type JsonValue =
|
||||
| <a href="#jsonobject">JsonObject</a>
|
||||
| <a href="#jsonarray">JsonArray</a>
|
||||
| number
|
||||
| string
|
||||
| boolean
|
||||
| null
|
||||
</pre>
|
||||
|
||||
Defined at
|
||||
[packages/config/src/types.ts:19](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/config/src/types.ts#L19).
|
||||
|
||||
Referenced by: [get](#get), [getOptional](#getoptional),
|
||||
[JsonObject](#jsonobject), [JsonArray](#jsonarray), [Config](#config).
|
||||
@@ -1,24 +0,0 @@
|
||||
# DiscoveryApi
|
||||
|
||||
The DiscoveryApi type is defined at
|
||||
[packages/core-api/src/apis/definitions/DiscoveryApi.ts:30](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/DiscoveryApi.ts#L30).
|
||||
|
||||
The following Utility API implements this type:
|
||||
[discoveryApiRef](./README.md#discovery)
|
||||
|
||||
## Members
|
||||
|
||||
### getBaseUrl()
|
||||
|
||||
Returns the HTTP base backend URL for a given plugin, without a trailing slash.
|
||||
|
||||
This method must always be called just before making a request, as opposed to
|
||||
fetching the URL when constructing an API client. That is to ensure that more
|
||||
flexible routing patterns can be supported.
|
||||
|
||||
For example, asking for the URL for `auth` may return something like
|
||||
`https://backstage.example.com/api/auth`
|
||||
|
||||
<pre>
|
||||
getBaseUrl(pluginId: string): Promise<string>
|
||||
</pre>
|
||||
@@ -1,134 +0,0 @@
|
||||
# ErrorApi
|
||||
|
||||
The ErrorApi type is defined at
|
||||
[packages/core-api/src/apis/definitions/ErrorApi.ts:53](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/ErrorApi.ts#L53).
|
||||
|
||||
The following Utility API implements this type: [errorApiRef](./README.md#error)
|
||||
|
||||
## Members
|
||||
|
||||
### post()
|
||||
|
||||
Post an error for handling by the application.
|
||||
|
||||
<pre>
|
||||
post(error: <a href="#error">Error</a>, context?: <a href="#errorcontext">ErrorContext</a>): void
|
||||
</pre>
|
||||
|
||||
### error\$()
|
||||
|
||||
Observe errors posted by other parts of the application.
|
||||
|
||||
<pre>
|
||||
error$(): <a href="#observable">Observable</a><{ error: <a href="#error">Error</a>; context?: <a href="#errorcontext">ErrorContext</a> }>
|
||||
</pre>
|
||||
|
||||
## Supporting types
|
||||
|
||||
These types are part of the API declaration, but may not be unique to this API.
|
||||
|
||||
### Error
|
||||
|
||||
Mirrors the JavaScript Error class, for the purpose of providing documentation
|
||||
and optional fields.
|
||||
|
||||
<pre>
|
||||
type Error = {
|
||||
name: string;
|
||||
message: string;
|
||||
stack?: string;
|
||||
}
|
||||
</pre>
|
||||
|
||||
Defined at
|
||||
[packages/core-api/src/apis/definitions/ErrorApi.ts:24](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/ErrorApi.ts#L24).
|
||||
|
||||
Referenced by: [post](#post), [error\$](#error).
|
||||
|
||||
### ErrorContext
|
||||
|
||||
Provides additional information about an error that was posted to the
|
||||
application.
|
||||
|
||||
<pre>
|
||||
export type ErrorContext = {
|
||||
// If set to true, this error should not be displayed to the user. Defaults to false.
|
||||
hidden?: boolean;
|
||||
}
|
||||
</pre>
|
||||
|
||||
Defined at
|
||||
[packages/core-api/src/apis/definitions/ErrorApi.ts:33](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/ErrorApi.ts#L33).
|
||||
|
||||
Referenced by: [post](#post), [error\$](#error).
|
||||
|
||||
### Observable
|
||||
|
||||
Observable sequence of values and errors, see TC39.
|
||||
|
||||
https://github.com/tc39/proposal-observable
|
||||
|
||||
This is used as a common return type for observable values and can be created
|
||||
using many different observable implementations, such as zen-observable or
|
||||
RxJS 5.
|
||||
|
||||
<pre>
|
||||
export type Observable<T> = {
|
||||
/**
|
||||
* Subscribes to this observable to start receiving new values.
|
||||
*/
|
||||
subscribe(observer: <a href="#observer">Observer</a><T>): <a href="#subscription">Subscription</a>;
|
||||
subscribe(
|
||||
onNext: (value: T) => void,
|
||||
onError?: (error: Error) => void,
|
||||
onComplete?: () => void,
|
||||
): <a href="#subscription">Subscription</a>;
|
||||
}
|
||||
</pre>
|
||||
|
||||
Defined at
|
||||
[packages/core-api/src/types.ts:53](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/types.ts#L53).
|
||||
|
||||
Referenced by: [error\$](#error).
|
||||
|
||||
### Observer
|
||||
|
||||
This file contains non-react related core types used throughout Backstage.
|
||||
|
||||
Observer interface for consuming an Observer, see TC39.
|
||||
|
||||
<pre>
|
||||
export type Observer<T> = {
|
||||
next?(value: T): void;
|
||||
error?(error: Error): void;
|
||||
complete?(): void;
|
||||
}
|
||||
</pre>
|
||||
|
||||
Defined at
|
||||
[packages/core-api/src/types.ts:24](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/types.ts#L24).
|
||||
|
||||
Referenced by: [Observable](#observable).
|
||||
|
||||
### Subscription
|
||||
|
||||
Subscription returned when subscribing to an Observable, see TC39.
|
||||
|
||||
<pre>
|
||||
export type Subscription = {
|
||||
/**
|
||||
* Cancels the subscription
|
||||
*/
|
||||
unsubscribe(): void;
|
||||
|
||||
/**
|
||||
* Value indicating whether the subscription is closed.
|
||||
*/
|
||||
readonly closed: Boolean;
|
||||
}
|
||||
</pre>
|
||||
|
||||
Defined at
|
||||
[packages/core-api/src/types.ts:33](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/types.ts#L33).
|
||||
|
||||
Referenced by: [Observable](#observable).
|
||||
@@ -1,113 +0,0 @@
|
||||
# FeatureFlagsApi
|
||||
|
||||
The FeatureFlagsApi type is defined at
|
||||
[packages/core-api/src/apis/definitions/FeatureFlagsApi.ts:60](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/FeatureFlagsApi.ts#L60).
|
||||
|
||||
The following Utility API implements this type:
|
||||
[featureFlagsApiRef](./README.md#featureflags)
|
||||
|
||||
## Members
|
||||
|
||||
### registerFlag()
|
||||
|
||||
Registers a new feature flag. Once a feature flag has been registered it can be
|
||||
toggled by users, and read back to enable or disable features.
|
||||
|
||||
<pre>
|
||||
registerFlag(flag: <a href="#featureflag">FeatureFlag</a>): void
|
||||
</pre>
|
||||
|
||||
### getRegisteredFlags()
|
||||
|
||||
Get a list of all registered flags.
|
||||
|
||||
<pre>
|
||||
getRegisteredFlags(): <a href="#featureflag">FeatureFlag</a>[]
|
||||
</pre>
|
||||
|
||||
### isActive()
|
||||
|
||||
Whether the feature flag with the given name is currently activated for the
|
||||
user.
|
||||
|
||||
<pre>
|
||||
isActive(name: string): boolean
|
||||
</pre>
|
||||
|
||||
### save()
|
||||
|
||||
Save the user's choice of feature flag states.
|
||||
|
||||
<pre>
|
||||
save(options: <a href="#featureflagssaveoptions">FeatureFlagsSaveOptions</a>): void
|
||||
</pre>
|
||||
|
||||
## Supporting types
|
||||
|
||||
These types are part of the API declaration, but may not be unique to this API.
|
||||
|
||||
### FeatureFlag
|
||||
|
||||
The feature flags API is used to toggle functionality to users across plugins
|
||||
and Backstage.
|
||||
|
||||
Plugins can use this API to register feature flags that they have available for
|
||||
users to enable/disable, and this API will centralize the current user's state
|
||||
of which feature flags they would like to enable.
|
||||
|
||||
This is ideal for Backstage plugins, as well as your own App, to trial
|
||||
incomplete or unstable upcoming features. Although there will be a common
|
||||
interface for users to enable and disable feature flags, this API acts as
|
||||
another way to enable/disable.
|
||||
|
||||
<pre>
|
||||
export type FeatureFlag = {
|
||||
name: string;
|
||||
pluginId: string;
|
||||
}
|
||||
</pre>
|
||||
|
||||
Defined at
|
||||
[packages/core-api/src/apis/definitions/FeatureFlagsApi.ts:31](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/FeatureFlagsApi.ts#L31).
|
||||
|
||||
Referenced by: [registerFlag](#registerflag),
|
||||
[getRegisteredFlags](#getregisteredflags).
|
||||
|
||||
### FeatureFlagState
|
||||
|
||||
<pre>
|
||||
export enum FeatureFlagState {
|
||||
None = 0,
|
||||
Active = 1,
|
||||
}
|
||||
</pre>
|
||||
|
||||
Defined at
|
||||
[packages/core-api/src/apis/definitions/FeatureFlagsApi.ts:36](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/FeatureFlagsApi.ts#L36).
|
||||
|
||||
Referenced by: [FeatureFlagsSaveOptions](#featureflagssaveoptions).
|
||||
|
||||
### FeatureFlagsSaveOptions
|
||||
|
||||
Options to use when saving feature flags.
|
||||
|
||||
<pre>
|
||||
export type FeatureFlagsSaveOptions = {
|
||||
/**
|
||||
* The new feature flag states to save.
|
||||
*/
|
||||
states: Record<string, <a href="#featureflagstate">FeatureFlagState</a>>;
|
||||
|
||||
/**
|
||||
* Whether the saves states should be merged into the existing ones, or replace them.
|
||||
*
|
||||
* Defaults to false.
|
||||
*/
|
||||
merge?: boolean;
|
||||
}
|
||||
</pre>
|
||||
|
||||
Defined at
|
||||
[packages/core-api/src/apis/definitions/FeatureFlagsApi.ts:44](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/FeatureFlagsApi.ts#L44).
|
||||
|
||||
Referenced by: [save](#save).
|
||||
@@ -1,81 +0,0 @@
|
||||
# IdentityApi
|
||||
|
||||
The IdentityApi type is defined at
|
||||
[packages/core-api/src/apis/definitions/IdentityApi.ts:22](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/IdentityApi.ts#L22).
|
||||
|
||||
The following Utility API implements this type:
|
||||
[identityApiRef](./README.md#identity)
|
||||
|
||||
## Members
|
||||
|
||||
### getUserId()
|
||||
|
||||
The ID of the signed in user. This ID is not meant to be presented to the user,
|
||||
but used as an opaque string to pass on to backends or use in frontend logic.
|
||||
|
||||
TODO: The intention of the user ID is to be able to tie the user to an identity
|
||||
that is known by the catalog and/or identity backend. It should for example be
|
||||
possible to fetch all owned components using this ID.
|
||||
|
||||
<pre>
|
||||
getUserId(): string
|
||||
</pre>
|
||||
|
||||
### getProfile()
|
||||
|
||||
The profile of the signed in user.
|
||||
|
||||
<pre>
|
||||
getProfile(): <a href="#profileinfo">ProfileInfo</a>
|
||||
</pre>
|
||||
|
||||
### getIdToken()
|
||||
|
||||
An OpenID Connect ID Token which proves the identity of the signed in user.
|
||||
|
||||
The ID token will be undefined if the signed in user does not have a verified
|
||||
identity, such as a demo user or mocked user for e2e tests.
|
||||
|
||||
<pre>
|
||||
getIdToken(): Promise<string | undefined>
|
||||
</pre>
|
||||
|
||||
### signOut()
|
||||
|
||||
Sign out the current user
|
||||
|
||||
<pre>
|
||||
signOut(): Promise<void>
|
||||
</pre>
|
||||
|
||||
## Supporting types
|
||||
|
||||
These types are part of the API declaration, but may not be unique to this API.
|
||||
|
||||
### ProfileInfo
|
||||
|
||||
Profile information of the user.
|
||||
|
||||
<pre>
|
||||
export type ProfileInfo = {
|
||||
/**
|
||||
* Email ID.
|
||||
*/
|
||||
email?: string;
|
||||
|
||||
/**
|
||||
* Display name that can be presented to the user.
|
||||
*/
|
||||
displayName?: string;
|
||||
|
||||
/**
|
||||
* URL to an avatar image of the user.
|
||||
*/
|
||||
picture?: string;
|
||||
}
|
||||
</pre>
|
||||
|
||||
Defined at
|
||||
[packages/core-api/src/apis/definitions/auth.ts:162](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/auth.ts#L162).
|
||||
|
||||
Referenced by: [getProfile](#getprofile).
|
||||
@@ -1,117 +0,0 @@
|
||||
# OAuthApi
|
||||
|
||||
The OAuthApi type is defined at
|
||||
[packages/core-api/src/apis/definitions/auth.ts:67](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/auth.ts#L67).
|
||||
|
||||
The following Utility APIs implement this type:
|
||||
|
||||
- [githubAuthApiRef](./README.md#githubauth)
|
||||
|
||||
- [gitlabAuthApiRef](./README.md#gitlabauth)
|
||||
|
||||
- [googleAuthApiRef](./README.md#googleauth)
|
||||
|
||||
- [microsoftAuthApiRef](./README.md#microsoftauth)
|
||||
|
||||
- [oauth2ApiRef](./README.md#oauth2)
|
||||
|
||||
- [oidcAuthApiRef](./README.md#oidcauth)
|
||||
|
||||
- [oktaAuthApiRef](./README.md#oktaauth)
|
||||
|
||||
- [oneloginAuthApiRef](./README.md#oneloginauth)
|
||||
|
||||
## Members
|
||||
|
||||
### getAccessToken()
|
||||
|
||||
Requests an OAuth 2 Access Token, optionally with a set of scopes. The access
|
||||
token allows you to make requests on behalf of the user, and the copes may grant
|
||||
you broader access, depending on the auth provider.
|
||||
|
||||
Each auth provider has separate handling of scope, so you need to look at the
|
||||
documentation for each one to know what scope you need to request.
|
||||
|
||||
This method is cheap and should be called each time an access token is used. Do
|
||||
not for example store the access token in React component state, as that could
|
||||
cause the token to expire. Instead fetch a new access token for each request.
|
||||
|
||||
Be sure to include all required scopes when requesting an access token. When
|
||||
testing your implementation it is best to log out the Backstage session and then
|
||||
visit your plugin page directly, as you might already have some required scopes
|
||||
in your existing session. Not requesting the correct scopes can lead to 403 or
|
||||
other authorization errors, which can be tricky to debug.
|
||||
|
||||
If the user has not yet granted access to the provider and the set of requested
|
||||
scopes, the user will be prompted to log in. The returned promise will not
|
||||
resolve until the user has successfully logged in. The returned promise can be
|
||||
rejected, but only if the user rejects the login request.
|
||||
|
||||
<pre>
|
||||
getAccessToken(
|
||||
scope?: <a href="#oauthscope">OAuthScope</a>,
|
||||
options?: <a href="#authrequestoptions">AuthRequestOptions</a>,
|
||||
): Promise<string>
|
||||
</pre>
|
||||
|
||||
## Supporting types
|
||||
|
||||
These types are part of the API declaration, but may not be unique to this API.
|
||||
|
||||
### AuthRequestOptions
|
||||
|
||||
<pre>
|
||||
export type AuthRequestOptions = {
|
||||
/**
|
||||
* If this is set to true, the user will not be prompted to log in,
|
||||
* and an empty response will be returned if there is no existing session.
|
||||
*
|
||||
* This can be used to perform a check whether the user is logged in, or if you don't
|
||||
* want to force a user to be logged in, but provide functionality if they already are.
|
||||
*
|
||||
* @default false
|
||||
*/
|
||||
optional?: boolean;
|
||||
|
||||
/**
|
||||
* If this is set to true, the request will bypass the regular oauth login modal
|
||||
* and open the login popup directly.
|
||||
*
|
||||
* The method must be called synchronously from a user action for this to work in all browsers.
|
||||
*
|
||||
* @default false
|
||||
*/
|
||||
instantPopup?: boolean;
|
||||
}
|
||||
</pre>
|
||||
|
||||
Defined at
|
||||
[packages/core-api/src/apis/definitions/auth.ts:40](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/auth.ts#L40).
|
||||
|
||||
Referenced by: [getAccessToken](#getaccesstoken).
|
||||
|
||||
### OAuthScope
|
||||
|
||||
This file contains declarations for common interfaces of auth-related APIs. The
|
||||
declarations should be used to signal which type of authentication and
|
||||
authorization methods each separate auth provider supports.
|
||||
|
||||
For example, a Google OAuth provider that supports OAuth 2 and OpenID Connect,
|
||||
would be declared as follows:
|
||||
|
||||
const googleAuthApiRef = createApiRef<OAuthApi & OpenIDConnectApi>({ ... })
|
||||
|
||||
An array of scopes, or a scope string formatted according to the auth provider,
|
||||
which is typically a space separated list.
|
||||
|
||||
See the documentation for each auth provider for the list of scopes supported by
|
||||
each provider.
|
||||
|
||||
<pre>
|
||||
export type OAuthScope = string | string[]
|
||||
</pre>
|
||||
|
||||
Defined at
|
||||
[packages/core-api/src/apis/definitions/auth.ts:38](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/auth.ts#L38).
|
||||
|
||||
Referenced by: [getAccessToken](#getaccesstoken).
|
||||
@@ -1,233 +0,0 @@
|
||||
# OAuthRequestApi
|
||||
|
||||
The OAuthRequestApi type is defined at
|
||||
[packages/core-api/src/apis/definitions/OAuthRequestApi.ts:99](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/OAuthRequestApi.ts#L99).
|
||||
|
||||
The following Utility API implements this type:
|
||||
[oauthRequestApiRef](./README.md#oauthrequest)
|
||||
|
||||
## Members
|
||||
|
||||
### createAuthRequester()
|
||||
|
||||
A utility for showing login popups or similar things, and merging together
|
||||
multiple requests for different scopes into one request that includes all
|
||||
scopes.
|
||||
|
||||
The passed in options provide information about the login provider, and how to
|
||||
handle auth requests.
|
||||
|
||||
The returned AuthRequester function is used to request login with new scopes.
|
||||
These requests are merged together and forwarded to the auth handler, as soon as
|
||||
a consumer of auth requests triggers an auth flow.
|
||||
|
||||
See AuthRequesterOptions, AuthRequester, and handleAuthRequests for more info.
|
||||
|
||||
<pre>
|
||||
createAuthRequester<AuthResponse>(
|
||||
options: <a href="#authrequesteroptions">AuthRequesterOptions</a><AuthResponse>,
|
||||
): <a href="#authrequester">AuthRequester</a><AuthResponse>
|
||||
</pre>
|
||||
|
||||
### authRequest\$()
|
||||
|
||||
Observers pending auth requests. The returned observable will emit all current
|
||||
active auth request, at most one for each created auth requester.
|
||||
|
||||
Each request has its own info about the login provider, forwarded from the auth
|
||||
requester options.
|
||||
|
||||
Depending on user interaction, the request should either be rejected, or used to
|
||||
trigger the auth handler. If the request is rejected, all pending AuthRequester
|
||||
calls will fail with a "RejectedError". If a auth is triggered, and the auth
|
||||
handler resolves successfully, then all currently pending AuthRequester calls
|
||||
will resolve to the value returned by the onAuthRequest call.
|
||||
|
||||
<pre>
|
||||
authRequest$(): <a href="#observable">Observable</a><<a href="#pendingauthrequest">PendingAuthRequest</a>[]>
|
||||
</pre>
|
||||
|
||||
## Supporting types
|
||||
|
||||
These types are part of the API declaration, but may not be unique to this API.
|
||||
|
||||
### AuthProvider
|
||||
|
||||
Information about the auth provider that we're requesting a login towards.
|
||||
|
||||
This should be shown to the user so that they can be informed about what login
|
||||
is being requested before a popup is shown.
|
||||
|
||||
<pre>
|
||||
export type AuthProvider = {
|
||||
/**
|
||||
* Title for the auth provider, for example "GitHub"
|
||||
*/
|
||||
title: string;
|
||||
|
||||
/**
|
||||
* Icon for the auth provider.
|
||||
*/
|
||||
icon: IconComponent;
|
||||
}
|
||||
</pre>
|
||||
|
||||
Defined at
|
||||
[packages/core-api/src/apis/definitions/OAuthRequestApi.ts:27](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/OAuthRequestApi.ts#L27).
|
||||
|
||||
Referenced by: [AuthRequesterOptions](#authrequesteroptions),
|
||||
[PendingAuthRequest](#pendingauthrequest).
|
||||
|
||||
### AuthRequester
|
||||
|
||||
Function used to trigger new auth requests for a set of scopes.
|
||||
|
||||
The returned promise will resolve to the same value returned by the
|
||||
onAuthRequest in the AuthRequesterOptions. Or rejected, if the request is
|
||||
rejected.
|
||||
|
||||
This function can be called multiple times before the promise resolves. All
|
||||
calls will be merged into one request, and the scopes forwarded to the
|
||||
onAuthRequest will be the union of all requested scopes.
|
||||
|
||||
<pre>
|
||||
export type AuthRequester<AuthResponse> = (
|
||||
scopes: Set<string>,
|
||||
) => Promise<AuthResponse>
|
||||
</pre>
|
||||
|
||||
Defined at
|
||||
[packages/core-api/src/apis/definitions/OAuthRequestApi.ts:66](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/OAuthRequestApi.ts#L66).
|
||||
|
||||
Referenced by: [createAuthRequester](#createauthrequester).
|
||||
|
||||
### AuthRequesterOptions
|
||||
|
||||
Describes how to handle auth requests. Both how to show them to the user, and
|
||||
what to do when the user accesses the auth request.
|
||||
|
||||
<pre>
|
||||
export type AuthRequesterOptions<AuthResponse> = {
|
||||
/**
|
||||
* Information about the auth provider, which will be forwarded to auth requests.
|
||||
*/
|
||||
provider: <a href="#authprovider">AuthProvider</a>;
|
||||
|
||||
/**
|
||||
* Implementation of the auth flow, which will be called synchronously when
|
||||
* trigger() is called on an auth requests.
|
||||
*/
|
||||
onAuthRequest(scopes: Set<string>): Promise<AuthResponse>;
|
||||
}
|
||||
</pre>
|
||||
|
||||
Defined at
|
||||
[packages/core-api/src/apis/definitions/OAuthRequestApi.ts:43](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/OAuthRequestApi.ts#L43).
|
||||
|
||||
Referenced by: [createAuthRequester](#createauthrequester).
|
||||
|
||||
### Observable
|
||||
|
||||
Observable sequence of values and errors, see TC39.
|
||||
|
||||
https://github.com/tc39/proposal-observable
|
||||
|
||||
This is used as a common return type for observable values and can be created
|
||||
using many different observable implementations, such as zen-observable or
|
||||
RxJS 5.
|
||||
|
||||
<pre>
|
||||
export type Observable<T> = {
|
||||
/**
|
||||
* Subscribes to this observable to start receiving new values.
|
||||
*/
|
||||
subscribe(observer: <a href="#observer">Observer</a><T>): <a href="#subscription">Subscription</a>;
|
||||
subscribe(
|
||||
onNext: (value: T) => void,
|
||||
onError?: (error: Error) => void,
|
||||
onComplete?: () => void,
|
||||
): <a href="#subscription">Subscription</a>;
|
||||
}
|
||||
</pre>
|
||||
|
||||
Defined at
|
||||
[packages/core-api/src/types.ts:53](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/types.ts#L53).
|
||||
|
||||
Referenced by: [authRequest\$](#authrequest).
|
||||
|
||||
### Observer
|
||||
|
||||
This file contains non-react related core types used throughout Backstage.
|
||||
|
||||
Observer interface for consuming an Observer, see TC39.
|
||||
|
||||
<pre>
|
||||
export type Observer<T> = {
|
||||
next?(value: T): void;
|
||||
error?(error: Error): void;
|
||||
complete?(): void;
|
||||
}
|
||||
</pre>
|
||||
|
||||
Defined at
|
||||
[packages/core-api/src/types.ts:24](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/types.ts#L24).
|
||||
|
||||
Referenced by: [Observable](#observable).
|
||||
|
||||
### PendingAuthRequest
|
||||
|
||||
An pending auth request for a single auth provider. The request will remain in
|
||||
this pending state until either reject() or trigger() is called.
|
||||
|
||||
Any new requests for the same provider are merged into the existing pending
|
||||
request, meaning there will only ever be a single pending request for a given
|
||||
provider.
|
||||
|
||||
<pre>
|
||||
export type PendingAuthRequest = {
|
||||
/**
|
||||
* Information about the auth provider, as given in the AuthRequesterOptions
|
||||
*/
|
||||
provider: <a href="#authprovider">AuthProvider</a>;
|
||||
|
||||
/**
|
||||
* Rejects the request, causing all pending AuthRequester calls to fail with "RejectedError".
|
||||
*/
|
||||
reject: () => void;
|
||||
|
||||
/**
|
||||
* Trigger the auth request to continue the auth flow, by for example showing a popup.
|
||||
*
|
||||
* Synchronously calls onAuthRequest with all scope currently in the request.
|
||||
*/
|
||||
trigger(): Promise<void>;
|
||||
}
|
||||
</pre>
|
||||
|
||||
Defined at
|
||||
[packages/core-api/src/apis/definitions/OAuthRequestApi.ts:77](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/OAuthRequestApi.ts#L77).
|
||||
|
||||
Referenced by: [authRequest\$](#authrequest).
|
||||
|
||||
### Subscription
|
||||
|
||||
Subscription returned when subscribing to an Observable, see TC39.
|
||||
|
||||
<pre>
|
||||
export type Subscription = {
|
||||
/**
|
||||
* Cancels the subscription
|
||||
*/
|
||||
unsubscribe(): void;
|
||||
|
||||
/**
|
||||
* Value indicating whether the subscription is closed.
|
||||
*/
|
||||
readonly closed: Boolean;
|
||||
}
|
||||
</pre>
|
||||
|
||||
Defined at
|
||||
[packages/core-api/src/types.ts:33](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/types.ts#L33).
|
||||
|
||||
Referenced by: [Observable](#observable).
|
||||
@@ -1,75 +0,0 @@
|
||||
# OpenIdConnectApi
|
||||
|
||||
The OpenIdConnectApi type is defined at
|
||||
[packages/core-api/src/apis/definitions/auth.ts:99](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/auth.ts#L99).
|
||||
|
||||
The following Utility APIs implement this type:
|
||||
|
||||
- [auth0AuthApiRef](./README.md#auth0auth)
|
||||
|
||||
- [googleAuthApiRef](./README.md#googleauth)
|
||||
|
||||
- [microsoftAuthApiRef](./README.md#microsoftauth)
|
||||
|
||||
- [oauth2ApiRef](./README.md#oauth2)
|
||||
|
||||
- [oidcAuthApiRef](./README.md#oidcauth)
|
||||
|
||||
- [oktaAuthApiRef](./README.md#oktaauth)
|
||||
|
||||
- [oneloginAuthApiRef](./README.md#oneloginauth)
|
||||
|
||||
## Members
|
||||
|
||||
### getIdToken()
|
||||
|
||||
Requests an OpenID Connect ID Token.
|
||||
|
||||
This method is cheap and should be called each time an ID token is used. Do not
|
||||
for example store the id token in React component state, as that could cause the
|
||||
token to expire. Instead fetch a new id token for each request.
|
||||
|
||||
If the user has not yet logged in to Google inside Backstage, the user will be
|
||||
prompted to log in. The returned promise will not resolve until the user has
|
||||
successfully logged in. The returned promise can be rejected, but only if the
|
||||
user rejects the login request.
|
||||
|
||||
<pre>
|
||||
getIdToken(options?: <a href="#authrequestoptions">AuthRequestOptions</a>): Promise<string>
|
||||
</pre>
|
||||
|
||||
## Supporting types
|
||||
|
||||
These types are part of the API declaration, but may not be unique to this API.
|
||||
|
||||
### AuthRequestOptions
|
||||
|
||||
<pre>
|
||||
export type AuthRequestOptions = {
|
||||
/**
|
||||
* If this is set to true, the user will not be prompted to log in,
|
||||
* and an empty response will be returned if there is no existing session.
|
||||
*
|
||||
* This can be used to perform a check whether the user is logged in, or if you don't
|
||||
* want to force a user to be logged in, but provide functionality if they already are.
|
||||
*
|
||||
* @default false
|
||||
*/
|
||||
optional?: boolean;
|
||||
|
||||
/**
|
||||
* If this is set to true, the request will bypass the regular oauth login modal
|
||||
* and open the login popup directly.
|
||||
*
|
||||
* The method must be called synchronously from a user action for this to work in all browsers.
|
||||
*
|
||||
* @default false
|
||||
*/
|
||||
instantPopup?: boolean;
|
||||
}
|
||||
</pre>
|
||||
|
||||
Defined at
|
||||
[packages/core-api/src/apis/definitions/auth.ts:40](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/auth.ts#L40).
|
||||
|
||||
Referenced by: [getIdToken](#getidtoken).
|
||||
@@ -1,104 +0,0 @@
|
||||
# ProfileInfoApi
|
||||
|
||||
The ProfileInfoApi type is defined at
|
||||
[packages/core-api/src/apis/definitions/auth.ts:117](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/auth.ts#L117).
|
||||
|
||||
The following Utility APIs implement this type:
|
||||
|
||||
- [auth0AuthApiRef](./README.md#auth0auth)
|
||||
|
||||
- [githubAuthApiRef](./README.md#githubauth)
|
||||
|
||||
- [gitlabAuthApiRef](./README.md#gitlabauth)
|
||||
|
||||
- [googleAuthApiRef](./README.md#googleauth)
|
||||
|
||||
- [microsoftAuthApiRef](./README.md#microsoftauth)
|
||||
|
||||
- [oauth2ApiRef](./README.md#oauth2)
|
||||
|
||||
- [oidcAuthApiRef](./README.md#oidcauth)
|
||||
|
||||
- [oktaAuthApiRef](./README.md#oktaauth)
|
||||
|
||||
- [oneloginAuthApiRef](./README.md#oneloginauth)
|
||||
|
||||
- [samlAuthApiRef](./README.md#samlauth)
|
||||
|
||||
## Members
|
||||
|
||||
### getProfile()
|
||||
|
||||
Get profile information for the user as supplied by this auth provider.
|
||||
|
||||
If the optional flag is not set, a session is guaranteed to be returned, while
|
||||
if the optional flag is set, the session may be undefined. See
|
||||
@AuthRequestOptions for more details.
|
||||
|
||||
<pre>
|
||||
getProfile(options?: <a href="#authrequestoptions">AuthRequestOptions</a>): Promise<<a href="#profileinfo">ProfileInfo</a> | undefined>
|
||||
</pre>
|
||||
|
||||
## Supporting types
|
||||
|
||||
These types are part of the API declaration, but may not be unique to this API.
|
||||
|
||||
### AuthRequestOptions
|
||||
|
||||
<pre>
|
||||
export type AuthRequestOptions = {
|
||||
/**
|
||||
* If this is set to true, the user will not be prompted to log in,
|
||||
* and an empty response will be returned if there is no existing session.
|
||||
*
|
||||
* This can be used to perform a check whether the user is logged in, or if you don't
|
||||
* want to force a user to be logged in, but provide functionality if they already are.
|
||||
*
|
||||
* @default false
|
||||
*/
|
||||
optional?: boolean;
|
||||
|
||||
/**
|
||||
* If this is set to true, the request will bypass the regular oauth login modal
|
||||
* and open the login popup directly.
|
||||
*
|
||||
* The method must be called synchronously from a user action for this to work in all browsers.
|
||||
*
|
||||
* @default false
|
||||
*/
|
||||
instantPopup?: boolean;
|
||||
}
|
||||
</pre>
|
||||
|
||||
Defined at
|
||||
[packages/core-api/src/apis/definitions/auth.ts:40](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/auth.ts#L40).
|
||||
|
||||
Referenced by: [getProfile](#getprofile).
|
||||
|
||||
### ProfileInfo
|
||||
|
||||
Profile information of the user.
|
||||
|
||||
<pre>
|
||||
export type ProfileInfo = {
|
||||
/**
|
||||
* Email ID.
|
||||
*/
|
||||
email?: string;
|
||||
|
||||
/**
|
||||
* Display name that can be presented to the user.
|
||||
*/
|
||||
displayName?: string;
|
||||
|
||||
/**
|
||||
* URL to an avatar image of the user.
|
||||
*/
|
||||
picture?: string;
|
||||
}
|
||||
</pre>
|
||||
|
||||
Defined at
|
||||
[packages/core-api/src/apis/definitions/auth.ts:162](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/auth.ts#L162).
|
||||
|
||||
Referenced by: [getProfile](#getprofile).
|
||||
@@ -1,202 +0,0 @@
|
||||
# Backstage Core Utility APIs
|
||||
|
||||
The following is a list of all Utility APIs defined by `@backstage/core`. They
|
||||
are available to use by plugins and components, and can be accessed using the
|
||||
`useApi` hook, also provided by `@backstage/core`. For more information, see
|
||||
https://github.com/backstage/backstage/blob/master/docs/api/utility-apis.md.
|
||||
|
||||
### alert
|
||||
|
||||
Used to report alerts and forward them to the app
|
||||
|
||||
Implemented type: [AlertApi](./AlertApi.md)
|
||||
|
||||
ApiRef:
|
||||
[alertApiRef](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/AlertApi.ts#L41)
|
||||
|
||||
### appTheme
|
||||
|
||||
API Used to configure the app theme, and enumerate options
|
||||
|
||||
Implemented type: [AppThemeApi](./AppThemeApi.md)
|
||||
|
||||
ApiRef:
|
||||
[appThemeApiRef](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/AppThemeApi.ts#L80)
|
||||
|
||||
### auth0Auth
|
||||
|
||||
Provides authentication towards Auth0 APIs
|
||||
|
||||
Implemented types: [OpenIdConnectApi](./OpenIdConnectApi.md),
|
||||
[ProfileInfoApi](./ProfileInfoApi.md),
|
||||
[BackstageIdentityApi](./BackstageIdentityApi.md), [SessionApi](./SessionApi.md)
|
||||
|
||||
ApiRef:
|
||||
[auth0AuthApiRef](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/auth.ts#L275)
|
||||
|
||||
### config
|
||||
|
||||
Used to access runtime configuration
|
||||
|
||||
Implemented type: [Config](./Config.md)
|
||||
|
||||
ApiRef:
|
||||
[configApiRef](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/ConfigApi.ts#L25)
|
||||
|
||||
### discovery
|
||||
|
||||
Provides service discovery of backend plugins
|
||||
|
||||
Implemented type: [DiscoveryApi](./DiscoveryApi.md)
|
||||
|
||||
ApiRef:
|
||||
[discoveryApiRef](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/DiscoveryApi.ts#L44)
|
||||
|
||||
### error
|
||||
|
||||
Used to report errors and forward them to the app
|
||||
|
||||
Implemented type: [ErrorApi](./ErrorApi.md)
|
||||
|
||||
ApiRef:
|
||||
[errorApiRef](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/ErrorApi.ts#L65)
|
||||
|
||||
### featureFlags
|
||||
|
||||
Used to toggle functionality in features across Backstage
|
||||
|
||||
Implemented type: [FeatureFlagsApi](./FeatureFlagsApi.md)
|
||||
|
||||
ApiRef:
|
||||
[featureFlagsApiRef](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/FeatureFlagsApi.ts#L83)
|
||||
|
||||
### githubAuth
|
||||
|
||||
Provides authentication towards GitHub APIs
|
||||
|
||||
Implemented types: [OAuthApi](./OAuthApi.md),
|
||||
[ProfileInfoApi](./ProfileInfoApi.md),
|
||||
[BackstageIdentityApi](./BackstageIdentityApi.md), [SessionApi](./SessionApi.md)
|
||||
|
||||
ApiRef:
|
||||
[githubAuthApiRef](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/auth.ts#L232)
|
||||
|
||||
### gitlabAuth
|
||||
|
||||
Provides authentication towards GitLab APIs
|
||||
|
||||
Implemented types: [OAuthApi](./OAuthApi.md),
|
||||
[ProfileInfoApi](./ProfileInfoApi.md),
|
||||
[BackstageIdentityApi](./BackstageIdentityApi.md), [SessionApi](./SessionApi.md)
|
||||
|
||||
ApiRef:
|
||||
[gitlabAuthApiRef](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/auth.ts#L262)
|
||||
|
||||
### googleAuth
|
||||
|
||||
Provides authentication towards Google APIs and identities
|
||||
|
||||
Implemented types: [OAuthApi](./OAuthApi.md),
|
||||
[OpenIdConnectApi](./OpenIdConnectApi.md),
|
||||
[ProfileInfoApi](./ProfileInfoApi.md),
|
||||
[BackstageIdentityApi](./BackstageIdentityApi.md), [SessionApi](./SessionApi.md)
|
||||
|
||||
ApiRef:
|
||||
[googleAuthApiRef](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/auth.ts#L215)
|
||||
|
||||
### identity
|
||||
|
||||
Provides access to the identity of the signed in user
|
||||
|
||||
Implemented type: [IdentityApi](./IdentityApi.md)
|
||||
|
||||
ApiRef:
|
||||
[identityApiRef](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/IdentityApi.ts#L53)
|
||||
|
||||
### microsoftAuth
|
||||
|
||||
Provides authentication towards Microsoft APIs and identities
|
||||
|
||||
Implemented types: [OAuthApi](./OAuthApi.md),
|
||||
[OpenIdConnectApi](./OpenIdConnectApi.md),
|
||||
[ProfileInfoApi](./ProfileInfoApi.md),
|
||||
[BackstageIdentityApi](./BackstageIdentityApi.md), [SessionApi](./SessionApi.md)
|
||||
|
||||
ApiRef:
|
||||
[microsoftAuthApiRef](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/auth.ts#L289)
|
||||
|
||||
### oauth2
|
||||
|
||||
Example of how to use oauth2 custom provider
|
||||
|
||||
Implemented types: [OAuthApi](./OAuthApi.md),
|
||||
[OpenIdConnectApi](./OpenIdConnectApi.md),
|
||||
[ProfileInfoApi](./ProfileInfoApi.md),
|
||||
[BackstageIdentityApi](./BackstageIdentityApi.md), [SessionApi](./SessionApi.md)
|
||||
|
||||
ApiRef:
|
||||
[oauth2ApiRef](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/auth.ts#L303)
|
||||
|
||||
### oauthRequest
|
||||
|
||||
An API for implementing unified OAuth flows in Backstage
|
||||
|
||||
Implemented type: [OAuthRequestApi](./OAuthRequestApi.md)
|
||||
|
||||
ApiRef:
|
||||
[oauthRequestApiRef](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/OAuthRequestApi.ts#L130)
|
||||
|
||||
### oidcAuth
|
||||
|
||||
Example of how to use oidc custom provider
|
||||
|
||||
Implemented types: [OAuthApi](./OAuthApi.md),
|
||||
[OpenIdConnectApi](./OpenIdConnectApi.md),
|
||||
[ProfileInfoApi](./ProfileInfoApi.md),
|
||||
[BackstageIdentityApi](./BackstageIdentityApi.md), [SessionApi](./SessionApi.md)
|
||||
|
||||
ApiRef:
|
||||
[oidcAuthApiRef](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/auth.ts#L317)
|
||||
|
||||
### oktaAuth
|
||||
|
||||
Provides authentication towards Okta APIs
|
||||
|
||||
Implemented types: [OAuthApi](./OAuthApi.md),
|
||||
[OpenIdConnectApi](./OpenIdConnectApi.md),
|
||||
[ProfileInfoApi](./ProfileInfoApi.md),
|
||||
[BackstageIdentityApi](./BackstageIdentityApi.md), [SessionApi](./SessionApi.md)
|
||||
|
||||
ApiRef:
|
||||
[oktaAuthApiRef](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/auth.ts#L245)
|
||||
|
||||
### oneloginAuth
|
||||
|
||||
Provides authentication towards OneLogin APIs and identities
|
||||
|
||||
Implemented types: [OAuthApi](./OAuthApi.md),
|
||||
[OpenIdConnectApi](./OpenIdConnectApi.md),
|
||||
[ProfileInfoApi](./ProfileInfoApi.md),
|
||||
[BackstageIdentityApi](./BackstageIdentityApi.md), [SessionApi](./SessionApi.md)
|
||||
|
||||
ApiRef:
|
||||
[oneloginAuthApiRef](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/auth.ts#L338)
|
||||
|
||||
### samlAuth
|
||||
|
||||
Example of how to use SAML custom provider
|
||||
|
||||
Implemented types: [ProfileInfoApi](./ProfileInfoApi.md),
|
||||
[BackstageIdentityApi](./BackstageIdentityApi.md), [SessionApi](./SessionApi.md)
|
||||
|
||||
ApiRef:
|
||||
[samlAuthApiRef](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/auth.ts#L331)
|
||||
|
||||
### storage
|
||||
|
||||
Provides the ability to store data which is unique to the user
|
||||
|
||||
Implemented type: [StorageApi](./StorageApi.md)
|
||||
|
||||
ApiRef:
|
||||
[storageApiRef](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/StorageApi.ts#L68)
|
||||
@@ -1,144 +0,0 @@
|
||||
# SessionApi
|
||||
|
||||
The SessionApi type is defined at
|
||||
[packages/core-api/src/apis/definitions/auth.ts:190](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/auth.ts#L190).
|
||||
|
||||
The following Utility APIs implement this type:
|
||||
|
||||
- [auth0AuthApiRef](./README.md#auth0auth)
|
||||
|
||||
- [githubAuthApiRef](./README.md#githubauth)
|
||||
|
||||
- [gitlabAuthApiRef](./README.md#gitlabauth)
|
||||
|
||||
- [googleAuthApiRef](./README.md#googleauth)
|
||||
|
||||
- [microsoftAuthApiRef](./README.md#microsoftauth)
|
||||
|
||||
- [oauth2ApiRef](./README.md#oauth2)
|
||||
|
||||
- [oidcAuthApiRef](./README.md#oidcauth)
|
||||
|
||||
- [oktaAuthApiRef](./README.md#oktaauth)
|
||||
|
||||
- [oneloginAuthApiRef](./README.md#oneloginauth)
|
||||
|
||||
- [samlAuthApiRef](./README.md#samlauth)
|
||||
|
||||
## Members
|
||||
|
||||
### signIn()
|
||||
|
||||
Sign in with a minimum set of permissions.
|
||||
|
||||
<pre>
|
||||
signIn(): Promise<void>
|
||||
</pre>
|
||||
|
||||
### signOut()
|
||||
|
||||
Sign out from the current session. This will reload the page.
|
||||
|
||||
<pre>
|
||||
signOut(): Promise<void>
|
||||
</pre>
|
||||
|
||||
### sessionState\$()
|
||||
|
||||
Observe the current state of the auth session. Emits the current state on
|
||||
subscription.
|
||||
|
||||
<pre>
|
||||
sessionState$(): <a href="#observable">Observable</a><<a href="#sessionstate">SessionState</a>>
|
||||
</pre>
|
||||
|
||||
## Supporting types
|
||||
|
||||
These types are part of the API declaration, but may not be unique to this API.
|
||||
|
||||
### Observable
|
||||
|
||||
Observable sequence of values and errors, see TC39.
|
||||
|
||||
https://github.com/tc39/proposal-observable
|
||||
|
||||
This is used as a common return type for observable values and can be created
|
||||
using many different observable implementations, such as zen-observable or
|
||||
RxJS 5.
|
||||
|
||||
<pre>
|
||||
export type Observable<T> = {
|
||||
/**
|
||||
* Subscribes to this observable to start receiving new values.
|
||||
*/
|
||||
subscribe(observer: <a href="#observer">Observer</a><T>): <a href="#subscription">Subscription</a>;
|
||||
subscribe(
|
||||
onNext: (value: T) => void,
|
||||
onError?: (error: Error) => void,
|
||||
onComplete?: () => void,
|
||||
): <a href="#subscription">Subscription</a>;
|
||||
}
|
||||
</pre>
|
||||
|
||||
Defined at
|
||||
[packages/core-api/src/types.ts:53](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/types.ts#L53).
|
||||
|
||||
Referenced by: [sessionState\$](#sessionstate).
|
||||
|
||||
### Observer
|
||||
|
||||
This file contains non-react related core types used throughout Backstage.
|
||||
|
||||
Observer interface for consuming an Observer, see TC39.
|
||||
|
||||
<pre>
|
||||
export type Observer<T> = {
|
||||
next?(value: T): void;
|
||||
error?(error: Error): void;
|
||||
complete?(): void;
|
||||
}
|
||||
</pre>
|
||||
|
||||
Defined at
|
||||
[packages/core-api/src/types.ts:24](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/types.ts#L24).
|
||||
|
||||
Referenced by: [Observable](#observable).
|
||||
|
||||
### SessionState
|
||||
|
||||
Session state values passed to subscribers of the SessionApi.
|
||||
|
||||
<pre>
|
||||
export enum SessionState {
|
||||
SignedIn = 'SignedIn',
|
||||
SignedOut = 'SignedOut',
|
||||
}
|
||||
</pre>
|
||||
|
||||
Defined at
|
||||
[packages/core-api/src/apis/definitions/auth.ts:182](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/auth.ts#L182).
|
||||
|
||||
Referenced by: [sessionState\$](#sessionstate).
|
||||
|
||||
### Subscription
|
||||
|
||||
Subscription returned when subscribing to an Observable, see TC39.
|
||||
|
||||
<pre>
|
||||
export type Subscription = {
|
||||
/**
|
||||
* Cancels the subscription
|
||||
*/
|
||||
unsubscribe(): void;
|
||||
|
||||
/**
|
||||
* Value indicating whether the subscription is closed.
|
||||
*/
|
||||
readonly closed: Boolean;
|
||||
}
|
||||
</pre>
|
||||
|
||||
Defined at
|
||||
[packages/core-api/src/types.ts:33](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/types.ts#L33).
|
||||
|
||||
Referenced by: [Observable](#observable).
|
||||
@@ -1,119 +0,0 @@
|
||||
# SessionStateApi
|
||||
|
||||
The SessionStateApi type is defined at
|
||||
[packages/core-api/src/apis/definitions/auth.ts:201](https://github.com/backstage/backstage/blob/82d329555c16af46db9b4e5cd2f44a3cc006a52e/packages/core-api/src/apis/definitions/auth.ts#L201).
|
||||
|
||||
The following Utility APIs implement this type:
|
||||
|
||||
- [auth0AuthApiRef](./README.md#auth0auth)
|
||||
|
||||
- [githubAuthApiRef](./README.md#githubauth)
|
||||
|
||||
- [gitlabAuthApiRef](./README.md#gitlabauth)
|
||||
|
||||
- [googleAuthApiRef](./README.md#googleauth)
|
||||
|
||||
- [microsoftAuthApiRef](./README.md#microsoftauth)
|
||||
|
||||
- [oauth2ApiRef](./README.md#oauth2)
|
||||
|
||||
- [oktaAuthApiRef](./README.md#oktaauth)
|
||||
|
||||
## Members
|
||||
|
||||
### sessionState\$()
|
||||
|
||||
<pre>
|
||||
sessionState$(): <a href="#observable">Observable</a><<a href="#sessionstate">SessionState</a>>
|
||||
</pre>
|
||||
|
||||
## Supporting types
|
||||
|
||||
These types are part of the API declaration, but may not be unique to this API.
|
||||
|
||||
### Observable
|
||||
|
||||
Observable sequence of values and errors, see TC39.
|
||||
|
||||
https://github.com/tc39/proposal-observable
|
||||
|
||||
This is used as a common return type for observable values and can be created
|
||||
using many different observable implementations, such as zen-observable or
|
||||
RxJS 5.
|
||||
|
||||
<pre>
|
||||
export type Observable<T> = {
|
||||
/**
|
||||
* Subscribes to this observable to start receiving new values.
|
||||
*/
|
||||
subscribe(observer: <a href="#observer">Observer</a><T>): <a href="#subscription">Subscription</a>;
|
||||
subscribe(
|
||||
onNext: (value: T) => void,
|
||||
onError?: (error: Error) => void,
|
||||
onComplete?: () => void,
|
||||
): <a href="#subscription">Subscription</a>;
|
||||
}
|
||||
</pre>
|
||||
|
||||
Defined at
|
||||
[packages/core-api/src/types.ts:53](https://github.com/backstage/backstage/blob/82d329555c16af46db9b4e5cd2f44a3cc006a52e/packages/core-api/src/types.ts#L53).
|
||||
|
||||
Referenced by: [sessionState\$](#sessionstate).
|
||||
|
||||
### Observer
|
||||
|
||||
This file contains non-react related core types used through Backstage.
|
||||
|
||||
Observer interface for consuming an Observer, see TC39.
|
||||
|
||||
<pre>
|
||||
export type Observer<T> = {
|
||||
next?(value: T): void;
|
||||
error?(error: Error): void;
|
||||
complete?(): void;
|
||||
}
|
||||
</pre>
|
||||
|
||||
Defined at
|
||||
[packages/core-api/src/types.ts:24](https://github.com/backstage/backstage/blob/82d329555c16af46db9b4e5cd2f44a3cc006a52e/packages/core-api/src/types.ts#L24).
|
||||
|
||||
Referenced by: [Observable](#observable).
|
||||
|
||||
### SessionState
|
||||
|
||||
Session state values passed to subscribers of the SessionStateApi.
|
||||
|
||||
<pre>
|
||||
export enum SessionState {
|
||||
SignedIn = 'SignedIn',
|
||||
SignedOut = 'SignedOut',
|
||||
}
|
||||
</pre>
|
||||
|
||||
Defined at
|
||||
[packages/core-api/src/apis/definitions/auth.ts:192](https://github.com/backstage/backstage/blob/82d329555c16af46db9b4e5cd2f44a3cc006a52e/packages/core-api/src/apis/definitions/auth.ts#L192).
|
||||
|
||||
Referenced by: [sessionState\$](#sessionstate).
|
||||
|
||||
### Subscription
|
||||
|
||||
Subscription returned when subscribing to an Observable, see TC39.
|
||||
|
||||
<pre>
|
||||
export type Subscription = {
|
||||
/**
|
||||
* Cancels the subscription
|
||||
*/
|
||||
unsubscribe(): void;
|
||||
|
||||
/**
|
||||
* Value indicating whether the subscription is closed.
|
||||
*/
|
||||
readonly closed: Boolean;
|
||||
}
|
||||
</pre>
|
||||
|
||||
Defined at
|
||||
[packages/core-api/src/types.ts:33](https://github.com/backstage/backstage/blob/82d329555c16af46db9b4e5cd2f44a3cc006a52e/packages/core-api/src/types.ts#L33).
|
||||
|
||||
Referenced by: [Observable](#observable).
|
||||
@@ -1,186 +0,0 @@
|
||||
# StorageApi
|
||||
|
||||
The StorageApi type is defined at
|
||||
[packages/core-api/src/apis/definitions/StorageApi.ts:31](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/StorageApi.ts#L31).
|
||||
|
||||
The following Utility API implements this type:
|
||||
[storageApiRef](./README.md#storage)
|
||||
|
||||
## Members
|
||||
|
||||
### forBucket()
|
||||
|
||||
Create a bucket to store data in.
|
||||
|
||||
<pre>
|
||||
forBucket(name: string): <a href="#storageapi">StorageApi</a>
|
||||
</pre>
|
||||
|
||||
### get()
|
||||
|
||||
Get the current value for persistent data, use observe\$ to be notified of
|
||||
updates.
|
||||
|
||||
<pre>
|
||||
get<T>(key: string): T | undefined
|
||||
</pre>
|
||||
|
||||
### remove()
|
||||
|
||||
Remove persistent data.
|
||||
|
||||
<pre>
|
||||
remove(key: string): Promise<void>
|
||||
</pre>
|
||||
|
||||
### set()
|
||||
|
||||
Save persistent data, and emit messages to anyone that is using observe\$ for
|
||||
this key
|
||||
|
||||
<pre>
|
||||
set(key: string, data: any): Promise<void>
|
||||
</pre>
|
||||
|
||||
### observe\$()
|
||||
|
||||
Observe changes on a particular key in the bucket
|
||||
|
||||
<pre>
|
||||
observe$<T>(key: string): <a href="#observable">Observable</a><<a href="#storagevaluechange">StorageValueChange</a><T>>
|
||||
</pre>
|
||||
|
||||
## Supporting types
|
||||
|
||||
These types are part of the API declaration, but may not be unique to this API.
|
||||
|
||||
### Observable
|
||||
|
||||
Observable sequence of values and errors, see TC39.
|
||||
|
||||
https://github.com/tc39/proposal-observable
|
||||
|
||||
This is used as a common return type for observable values and can be created
|
||||
using many different observable implementations, such as zen-observable or
|
||||
RxJS 5.
|
||||
|
||||
<pre>
|
||||
export type Observable<T> = {
|
||||
/**
|
||||
* Subscribes to this observable to start receiving new values.
|
||||
*/
|
||||
subscribe(observer: <a href="#observer">Observer</a><T>): <a href="#subscription">Subscription</a>;
|
||||
subscribe(
|
||||
onNext: (value: T) => void,
|
||||
onError?: (error: Error) => void,
|
||||
onComplete?: () => void,
|
||||
): <a href="#subscription">Subscription</a>;
|
||||
}
|
||||
</pre>
|
||||
|
||||
Defined at
|
||||
[packages/core-api/src/types.ts:53](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/types.ts#L53).
|
||||
|
||||
Referenced by: [observe\$](#observe), [StorageApi](#storageapi).
|
||||
|
||||
### Observer
|
||||
|
||||
This file contains non-react related core types used throughout Backstage.
|
||||
|
||||
Observer interface for consuming an Observer, see TC39.
|
||||
|
||||
<pre>
|
||||
export type Observer<T> = {
|
||||
next?(value: T): void;
|
||||
error?(error: Error): void;
|
||||
complete?(): void;
|
||||
}
|
||||
</pre>
|
||||
|
||||
Defined at
|
||||
[packages/core-api/src/types.ts:24](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/types.ts#L24).
|
||||
|
||||
Referenced by: [Observable](#observable).
|
||||
|
||||
### StorageApi
|
||||
|
||||
<pre>
|
||||
export interface StorageApi {
|
||||
/**
|
||||
* Create a bucket to store data in.
|
||||
* @param {String} name Namespace for the storage to be stored under,
|
||||
* will inherit previous namespaces too
|
||||
*/
|
||||
forBucket(name: string): StorageApi;
|
||||
|
||||
/**
|
||||
* Get the current value for persistent data, use observe$ to be notified of updates.
|
||||
*
|
||||
* @param {String} key Unique key associated with the data.
|
||||
* @return {Object} data The data that should is stored.
|
||||
*/
|
||||
get<T>(key: string): T | undefined;
|
||||
|
||||
/**
|
||||
* Remove persistent data.
|
||||
*
|
||||
* @param {String} key Unique key associated with the data.
|
||||
*/
|
||||
remove(key: string): Promise<void>;
|
||||
|
||||
/**
|
||||
* Save persistent data, and emit messages to anyone that is using observe$ for this key
|
||||
*
|
||||
* @param {String} key Unique key associated with the data.
|
||||
*/
|
||||
set(key: string, data: any): Promise<void>;
|
||||
|
||||
/**
|
||||
* Observe changes on a particular key in the bucket
|
||||
* @param {String} key Unique key associated with the data
|
||||
*/
|
||||
observe$<T>(key: string): <a href="#observable">Observable</a><<a href="#storagevaluechange">StorageValueChange</a><T>>;
|
||||
}
|
||||
</pre>
|
||||
|
||||
Defined at
|
||||
[packages/core-api/src/apis/definitions/StorageApi.ts:31](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/StorageApi.ts#L31).
|
||||
|
||||
Referenced by: [forBucket](#forbucket).
|
||||
|
||||
### StorageValueChange
|
||||
|
||||
<pre>
|
||||
export type StorageValueChange<T = any> = {
|
||||
key: string;
|
||||
newValue?: T;
|
||||
}
|
||||
</pre>
|
||||
|
||||
Defined at
|
||||
[packages/core-api/src/apis/definitions/StorageApi.ts:21](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/apis/definitions/StorageApi.ts#L21).
|
||||
|
||||
Referenced by: [observe\$](#observe), [StorageApi](#storageapi).
|
||||
|
||||
### Subscription
|
||||
|
||||
Subscription returned when subscribing to an Observable, see TC39.
|
||||
|
||||
<pre>
|
||||
export type Subscription = {
|
||||
/**
|
||||
* Cancels the subscription
|
||||
*/
|
||||
unsubscribe(): void;
|
||||
|
||||
/**
|
||||
* Value indicating whether the subscription is closed.
|
||||
*/
|
||||
readonly closed: Boolean;
|
||||
}
|
||||
</pre>
|
||||
|
||||
Defined at
|
||||
[packages/core-api/src/types.ts:33](https://github.com/backstage/backstage/blob/a4dbd8353cfa4d4d4334473e2c33afcda64e130d/packages/core-api/src/types.ts#L33).
|
||||
|
||||
Referenced by: [Observable](#observable).
|
||||
Reference in New Issue
Block a user