paulononato/backstage
1
0
Fork 0
Code Issues Pull Requests Actions 23 Packages Projects Releases Wiki Activity

docs: clear out the reference folder

Browse Source 
Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>
This commit is contained in:
Patrik Oldsberg
2021-09-12 11:45:46 +02:00
parent 6caa4df79b
commit 1a7340e1ae
20 changed files with 5 additions and 2302 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/reference/.generated
+2
View File
@@ -0,0 +1,2 @@
The contents of this folder is generated by the root `yarn build:api-docs` command.
Don't put any additional content here as it will be overwritten during the microsite build.
docs/reference/createPlugin-feature-flags.md
-44
View File
@@ -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>
);
};
```
docs/reference/createPlugin.md
-41
View File
@@ -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');
},
});
```
docs/reference/utility-apis/AlertApi.md
-114
View File
@@ -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>&lt;<a href="#alertmessage">AlertMessage</a>&gt;
</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&lt;T&gt; = {
/**
* Subscribes to this observable to start receiving new values.
*/
subscribe(observer: <a href="#observer">Observer</a>&lt;T&gt;): <a href="#subscription">Subscription</a>;
subscribe(
onNext: (value: T) =&gt; void,
onError?: (error: Error) =&gt; void,
onComplete?: () =&gt; 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&lt;T&gt; = {
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).
docs/reference/utility-apis/AppThemeApi.md
-271
View File
@@ -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>&lt;string | undefined&gt;
</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&lt;SvgIconProps&gt;;
}
</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 &amp; <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>) =&gt; <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&lt;T&gt; = {
/**
* Subscribes to this observable to start receiving new values.
*/
subscribe(observer: <a href="#observer">Observer</a>&lt;T&gt;): <a href="#subscription">Subscription</a>;
subscribe(
onNext: (value: T) =&gt; void,
onError?: (error: Error) =&gt; void,
onComplete?: () =&gt; 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&lt;T&gt; = {
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).
docs/reference/utility-apis/BackstageIdentityApi.md
-100
View File
@@ -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&lt;<a href="#backstageidentity">BackstageIdentity</a> | undefined&gt;
</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).
docs/reference/utility-apis/Config.md
-187
View File
@@ -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).
docs/reference/utility-apis/DiscoveryApi.md
-24
View File
@@ -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&lt;string&gt;
</pre>
docs/reference/utility-apis/ErrorApi.md
-134
View File
@@ -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>&lt;{ error: <a href="#error">Error</a>; context?: <a href="#errorcontext">ErrorContext</a> }&gt;
</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&lt;T&gt; = {
/**
* Subscribes to this observable to start receiving new values.
*/
subscribe(observer: <a href="#observer">Observer</a>&lt;T&gt;): <a href="#subscription">Subscription</a>;
subscribe(
onNext: (value: T) =&gt; void,
onError?: (error: Error) =&gt; void,
onComplete?: () =&gt; 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&lt;T&gt; = {
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).
docs/reference/utility-apis/FeatureFlagsApi.md
-113
View File
@@ -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&lt;string, <a href="#featureflagstate">FeatureFlagState</a>&gt;;
/**
* 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).
docs/reference/utility-apis/IdentityApi.md
-81
View File
@@ -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&lt;string | undefined&gt;
</pre>
### signOut()
Sign out the current user
<pre>
signOut(): Promise&lt;void&gt;
</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).
docs/reference/utility-apis/OAuthApi.md
-117
View File
@@ -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&lt;string&gt;
</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).
docs/reference/utility-apis/OAuthRequestApi.md
-233
View File
@@ -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&lt;AuthResponse&gt;(
options: <a href="#authrequesteroptions">AuthRequesterOptions</a>&lt;AuthResponse&gt;,
): <a href="#authrequester">AuthRequester</a>&lt;AuthResponse&gt;
</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>&lt;<a href="#pendingauthrequest">PendingAuthRequest</a>[]&gt;
</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&lt;AuthResponse&gt; = (
scopes: Set&lt;string&gt;,
) =&gt; Promise&lt;AuthResponse&gt;
</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&lt;AuthResponse&gt; = {
/**
* 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&lt;string&gt;): Promise&lt;AuthResponse&gt;;
}
</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&lt;T&gt; = {
/**
* Subscribes to this observable to start receiving new values.
*/
subscribe(observer: <a href="#observer">Observer</a>&lt;T&gt;): <a href="#subscription">Subscription</a>;
subscribe(
onNext: (value: T) =&gt; void,
onError?: (error: Error) =&gt; void,
onComplete?: () =&gt; 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&lt;T&gt; = {
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: () =&gt; 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&lt;void&gt;;
}
</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).
docs/reference/utility-apis/OpenIdConnectApi.md
-75
View File
@@ -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&lt;string&gt;
</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).
docs/reference/utility-apis/ProfileInfoApi.md
-104
View File
@@ -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&lt;<a href="#profileinfo">ProfileInfo</a> | undefined&gt;
</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).
docs/reference/utility-apis/README.md
-202
View File
@@ -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)
docs/reference/utility-apis/SessionApi.md
-144
View File
@@ -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&lt;void&gt;
</pre>
### signOut()
Sign out from the current session. This will reload the page.
<pre>
signOut(): Promise&lt;void&gt;
</pre>
### sessionState\$()
Observe the current state of the auth session. Emits the current state on
subscription.
<pre>
sessionState$(): <a href="#observable">Observable</a>&lt;<a href="#sessionstate">SessionState</a>&gt;
</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&lt;T&gt; = {
/**
* Subscribes to this observable to start receiving new values.
*/
subscribe(observer: <a href="#observer">Observer</a>&lt;T&gt;): <a href="#subscription">Subscription</a>;
subscribe(
onNext: (value: T) =&gt; void,
onError?: (error: Error) =&gt; void,
onComplete?: () =&gt; 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&lt;T&gt; = {
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).
docs/reference/utility-apis/SessionStateApi.md
-119
View File
@@ -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>&lt;<a href="#sessionstate">SessionState</a>&gt;
</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&lt;T&gt; = {
/**
* Subscribes to this observable to start receiving new values.
*/
subscribe(observer: <a href="#observer">Observer</a>&lt;T&gt;): <a href="#subscription">Subscription</a>;
subscribe(
onNext: (value: T) =&gt; void,
onError?: (error: Error) =&gt; void,
onComplete?: () =&gt; 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&lt;T&gt; = {
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).
docs/reference/utility-apis/StorageApi.md
-186
View File
@@ -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&lt;T&gt;(key: string): T | undefined
</pre>
### remove()
Remove persistent data.
<pre>
remove(key: string): Promise&lt;void&gt;
</pre>
### set()
Save persistent data, and emit messages to anyone that is using observe\$ for
this key
<pre>
set(key: string, data: any): Promise&lt;void&gt;
</pre>
### observe\$()
Observe changes on a particular key in the bucket
<pre>
observe$&lt;T&gt;(key: string): <a href="#observable">Observable</a>&lt;<a href="#storagevaluechange">StorageValueChange</a>&lt;T&gt;&gt;
</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&lt;T&gt; = {
/**
* Subscribes to this observable to start receiving new values.
*/
subscribe(observer: <a href="#observer">Observer</a>&lt;T&gt;): <a href="#subscription">Subscription</a>;
subscribe(
onNext: (value: T) =&gt; void,
onError?: (error: Error) =&gt; void,
onComplete?: () =&gt; 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&lt;T&gt; = {
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&lt;T&gt;(key: string): T | undefined;
/**
* Remove persistent data.
*
* @param {String} key Unique key associated with the data.
*/
remove(key: string): Promise&lt;void&gt;;
/**
* 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&lt;void&gt;;
/**
* Observe changes on a particular key in the bucket
* @param {String} key Unique key associated with the data
*/
observe$&lt;T&gt;(key: string): <a href="#observable">Observable</a>&lt;<a href="#storagevaluechange">StorageValueChange</a>&lt;T&gt;&gt;;
}
</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&lt;T = any&gt; = {
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).
microsite/sidebars.json
+3 -13
View File
@@ -234,21 +234,11 @@
"dls/contributing-to-storybook",
"dls/figma"
],
"API references": [
"API Reference": [
{
"type": "subcategory",
"label": "TypeScript API",
"ids": [
"api/utility-apis",
"reference/utility-apis/README",
"reference/createPlugin",
"reference/createPlugin-feature-flags"
]
},
{
"type": "subcategory",
"label": "Backend APIs",
"ids": ["api/backend"]
"label": "Guides",
"ids": [ "api/utility-apis" ]
}
],
"Tutorials": [