mirror of
https://github.com/Unleash/unleash.git
synced 2025-09-05 17:53:12 +02:00
Remove Enable OpernAPI and how to use Admin API
This commit is contained in:
melindafekete
parent
2db49795dc
commit
0c9c573d1a
@ -86,7 +86,7 @@ export const ApiTokenTable = ({
|
||||
<span>
|
||||
{'No tokens available. Read '}
|
||||
<Link
|
||||
href='https://docs.getunleash.io/how-to/api'
|
||||
href='https://docs.getunleash.io/api-overview'
|
||||
target='_blank'
|
||||
rel='noreferrer'
|
||||
>
|
||||
|
||||
@ -351,7 +351,7 @@ export const ProjectAccessAssign = ({
|
||||
modal
|
||||
title={`${!edit ? 'Assign' : 'Edit'} ${entityType} access`}
|
||||
description='Custom project roles allow you to fine-tune access rights and permissions within your projects.'
|
||||
documentationLink='https://docs.getunleash.io/reference/rbac/create-and-assign-a-custom-project-role'
|
||||
documentationLink='https://docs.getunleash.io/reference/rbac#create-and-assign-a-custom-project-role'
|
||||
documentationLinkLabel='Project access documentation'
|
||||
formatApiCode={formatApiCode}
|
||||
>
|
||||
|
||||
@ -9,3 +9,57 @@ displayed_sidebar: documentation
|
||||
## Client API
|
||||
|
||||
## Admin API
|
||||
|
||||
How to use the Admin API
|
||||
## Create API token
|
||||
|
||||
First, you'll need to create a [personal access token](/reference/api-tokens-and-client-keys.mdx#personal-access-tokens).
|
||||
|
||||
Please note that it may take up to 60 seconds for the new key to propagate to all Unleash instances due to eager caching.
|
||||
|
||||
:::note
|
||||
|
||||
If you need an API token to use in a client SDK you should create a client token instead, as these have fewer access rights.
|
||||
|
||||
:::
|
||||
|
||||
## Use Admin API
|
||||
|
||||
Now that you have an access token with admin privileges, you can use it to make changes in your Unleash instance.
|
||||
|
||||
In the example below we will use the [Unleash Admin API](/reference/api/legacy/unleash/admin/features.md) to enable the `checkout-flow` feature flag in `development` using curl.
|
||||
|
||||
```sh
|
||||
curl -X POST -H "Content-Type: application/json" \
|
||||
-H "Authorization: <your-token>" \
|
||||
https://app.unleash-hosted.com/docs-demo/api/admin/projects/docs-project/features/checkout-flow/environments/development/on
|
||||
```
|
||||
|
||||
We have now enabled the feature flag. We can also verify that it was actually changed by the API user by navigating to [Event Log](/reference/events#event-log) and filtering events for this feature flag.
|
||||
|
||||
|
||||
|
||||
You can find the full documentation on everything the Unleash API supports in the [Unleash API documentation](/reference/api/legacy/unleash/admin/features.md).
|
||||
|
||||
|
||||
## Enable and access the OpenAPI specification
|
||||
|
||||
:::note Availability
|
||||
|
||||
**Unleash version**: `4.13+`
|
||||
|
||||
:::
|
||||
|
||||
The Unleash server provides an OpenAPI specification that describes its APIs. This specification is useful for understanding the API, generating client libraries, or for testing purposes.
|
||||
|
||||
For self-hosted Unleash v5.2+, the OpenAPI specification endpoint is enabled by default. For older self-hosted versions, use the `ENABLE_OAS` [environment variable](/using-unleash/deploy/configuring-unleash) to enable it.
|
||||
|
||||
You can access the OpenAPI specification from your Unleash instance URL.
|
||||
|
||||
- **JSON Specification:**
|
||||
- Path: `/docs/openapi.json`
|
||||
- This provides the raw OpenAPI specification in JSON format.
|
||||
|
||||
- **Swagger UI (interactive documentation):**
|
||||
- Path: `/docs/openapi/`
|
||||
- This provides an interactive UI where you can explore and test the API endpoints.
|
||||
|
||||
@ -1,15 +1,12 @@
|
||||
---
|
||||
title: How to capture impression data
|
||||
title: Send impression data to analytics tools
|
||||
---
|
||||
|
||||
import ApiRequest from "@site/src/components/ApiRequest";
|
||||
import VideoContent from "@site/src/components/VideoContent.jsx";
|
||||
|
||||
:::info Placeholders
|
||||
Placeholders in the code samples below are delimited by angle brackets (i.e. `<placeholder-name>`). You will need to replace them with the values that are correct in _your_ situation for the code samples to run properly.
|
||||
:::
|
||||
|
||||
Unleash allows you to gather [**impression data**](../reference/impression-data) from your feature flags, giving you complete visibility into who checked what flags and when. What you do with this data is entirely up to you, but a common use case is to send it off to an aggregation and analytics service such as [Posthog](https://posthog.com/) or [Google Analytics](https://analytics.google.com/), either just for monitoring purposes or to facilitate [A/B testing](../feature-flag-tutorials/use-cases/a-b-testing).
|
||||
Unleash allows you to gather [impression data](../reference/impression-data) from your feature flags, giving you complete visibility into who checked what flags and when. What you do with this data is entirely up to you, but a common use case is to send it off to an aggregation and analytics service such as [Posthog](https://posthog.com/) or [Google Analytics](https://analytics.google.com/), either just for monitoring purposes or to facilitate [A/B testing](../feature-flag-tutorials/use-cases/a-b-testing).
|
||||
|
||||
This guide will take you through everything you need to do in Unleash to facilitate such a workflow. It will show you how to send data to Posthog as an example sink, but the exact same principles will apply to any other service of the same kind.
|
||||
|
||||
@ -26,11 +23,11 @@ In addition, you'll need to have a flag to record impression data for and an [Un
|
||||
|
||||
When you have those things sorted, follow the below steps.
|
||||
|
||||
## Step 1: Enable impression data for your feature flag {#step-1}
|
||||
## Enable impression data for your feature flag
|
||||
|
||||
Because impression data is an **opt-in feature**, the first step is to enable it for the feature you want to gather data from. You can use both the UI and the API.
|
||||
|
||||
### Enabling impression data for new feature flags {#step-1-new-toggles}
|
||||
### Enable impression data for new feature flags
|
||||
|
||||
When you create a new feature flag via the UI, there's an option at the end of the form that you must enable:
|
||||
|
||||
@ -45,7 +42,7 @@ To create a feature flag with impression data enabled, set the `impressionData`
|
||||
title="Create a feature flag with impression data enabled."
|
||||
/>
|
||||
|
||||
### Enabling impression data for existing feature flags {#step-1-existing-toggles}
|
||||
### Enable impression data for existing feature flags
|
||||
|
||||
To enable impression data for an existing flag, go to the "Settings" tab of that feature flag and use the "edit" button near the Feature information title in the admin UI. It will take you to a form that looks like the flag creation form. Use the "Enable impression data" flag to enable it, the same way you would when [enabling impression data for a new feature flag](#step-1-new-toggles).
|
||||
|
||||
@ -60,9 +57,9 @@ To enable impression data for an existing flag, use the [API's flag patching fun
|
||||
title="Enable impression data on an existing flag."
|
||||
/>
|
||||
|
||||
## Step 2: Capture impression events in your client {#step-2}
|
||||
## Capture impression events in your client
|
||||
|
||||
In your client SDK, initialize the library for the third party service you're using.
|
||||
In your client SDK, initialize the library for the third-party service you're using.
|
||||
For the full details on setting up a Posthog client, see [the official Posthog JavaScript client docs](https://posthog.com/docs/integrate/client/js).
|
||||
The steps below will use extracts from said documentation.
|
||||
|
||||
@ -88,7 +88,7 @@ Unleash is built with many mechanisms in place to handle all of these scenarios.
|
||||
|
||||
Let’s look at how Unleash gives you complete control over user roles and permissions. At a high level, there are multiple [predefined roles](/reference/rbac#predefined-roles) in Unleash for you to get started with. Root roles control permissions to top-level resources, spanning across all projects. Project roles, on the other hand, control permissions for a project, the feature flags, and individual configurations per environment.
|
||||
|
||||
The three predefined root roles are: Admin, Editor, and Viewer. The predefined project roles are Owner and Member. In addition to these, you can also create [custom root roles](/reference/rabc/create-and-assign-a-custom-root-role) or [project roles](/reference/rbac/create-and-assign-a-custom-project-role). The following diagram provides a visual overview of how root roles and project roles compare.
|
||||
The three predefined root roles are: Admin, Editor, and Viewer. The predefined project roles are Owner and Member. In addition to these, you can also create [custom root roles](/reference/rbac#create-and-assign-a-custom-root-role) or [project roles](/reference/rbac#create-and-assign-a-custom-project-role). The following diagram provides a visual overview of how root roles and project roles compare.
|
||||
|
||||
|
||||
|
||||
|
||||
@ -97,7 +97,7 @@ Viewers can observe projects and flags, but cannot make changes. When added to a
|
||||
|
||||
Project permissions are separated from root permissions to make it even more targeted regarding what permissions someone can and cannot have in Unleash.
|
||||
|
||||
For more fine-tuned access controls, create [custom root roles](/reference/rbac/create-and-assign-a-custom-root-role) and [custom project roles](/reference/rbac/create-and-assign-a-custom-project-role), where you can define the privileges and limitations beyond the predefined roles we have built into Unleash.
|
||||
For more fine-tuned access controls, create [custom root roles](/reference/rbac#create-and-assign-a-custom-root-role) and [custom project roles](/reference/rbac#create-and-assign-a-custom-project-role), where you can define the privileges and limitations beyond the predefined roles we have built into Unleash.
|
||||
|
||||
For example, customize root permissions to perform CRUD operations for:
|
||||
|
||||
|
||||
@ -1,125 +0,0 @@
|
||||
---
|
||||
title: How to enable OpenAPI and the Swagger UI
|
||||
---
|
||||
|
||||
import Tabs from '@theme/Tabs';
|
||||
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
:::note Availability
|
||||
|
||||
**Unleash version**: `4.13+` | **Unleash Proxy version**: `0.10+`
|
||||
|
||||
:::
|
||||
|
||||
Both Unleash and the Unleash proxy have included OpenAPI schemas and Swagger UIs for their APIs. The schemas can be used to get an overview of all API operations and to generate API clients using OpenAPI client generators. The Swagger UI lets you see and try out all the available API operations directly in your browser.
|
||||
|
||||
To enable the OpenAPI documentation and the Swagger UI, you must start Unleash or the proxy with the correct configuration option. The following section shows you how. The methods are the same for both Unleash and the Unleash proxy, so the steps described in the next section will work for either.
|
||||
|
||||
## Location of the OpenAPI spec
|
||||
|
||||
Once you enable OpenAPI, you can find the specification in JSON format at `/docs/openapi.json` and the swagger UI at `/docs/openapi`.
|
||||
|
||||
For instance, if you're running the Unleash server locally at `http://localhost:4242`, then
|
||||
|
||||
- the JSON specification will be at `http://localhost:4242/docs/openapi.json`
|
||||
- the Swagger UI will be at `http://localhost:4242/docs/openapi`
|
||||
|
||||
Similarly, if you're running the Unleash proxy locally at `http://localhost:3000` (so that the proxy endpoint is at `http://localhost:3000/proxy`), then
|
||||
|
||||
- the JSON specification will be at `http://localhost:3000/docs/openapi.json`
|
||||
- the Swagger UI will be at `http://localhost:3000/docs/openapi`
|
||||
|
||||
## Step 1: enable OpenAPI
|
||||
|
||||
The OpenAPI spec and the Swagger UI can be turned on either via environment variables or via configuration options. Configuration options take precedence over environment variables.
|
||||
|
||||
If you are using Unleash v5.2.0, OpenAPI is enabled by default. You still need to enable it for Unleash proxy.
|
||||
|
||||
### Enable OpenAPI via environment variables
|
||||
|
||||
To turn on OpenAPI via environment variables, set the `ENABLE_OAS` to `true` in the environment you're running the server in.
|
||||
|
||||
<Tabs groupId="openapi-env-configuration">
|
||||
|
||||
<TabItem value="bash" label="Environment variable (bash)" default>
|
||||
|
||||
```bash title="Enable OpenAPI via an environment variable"
|
||||
export ENABLE_OAS=true
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
|
||||
<TabItem value="docker-unleash" label="Docker (Unleash)">
|
||||
|
||||
```bash title="Enable OpenAPI for Unleash via Docker"
|
||||
docker run \
|
||||
// highlight-next-line
|
||||
-e ENABLE_OAS=true \ # other variables omitted for brevity
|
||||
unleashorg/unleash-server
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
|
||||
<TabItem value="docker-proxy" label="Docker (Unleash proxy)">
|
||||
|
||||
```bash title="Enable OpenAPI for the Unleash proxy via Docker"
|
||||
docker run \
|
||||
// highlight-next-line
|
||||
-e ENABLE_OAS=true \ # other variables omitted for brevity
|
||||
unleashorg/unleash-proxy
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
|
||||
</Tabs>
|
||||
|
||||
### Enable OpenAPI via configuration options
|
||||
|
||||
The configuration option for enabling OpenAPI and the swagger UI is `enableOAS`. Set this option to `true`.
|
||||
|
||||
The following examples have been shortened to show only the relevant configuration options. For more detailed instructions, refer to [our self-hosting guide](/using-unleash/deploy/getting-started).
|
||||
|
||||
<Tabs groupId="openapi-configuration">
|
||||
|
||||
<TabItem value="unleash" label="Unleash">
|
||||
|
||||
```js title="Enable OpenAPI for Unleash via configuration option"
|
||||
const unleash = require('unleash-server');
|
||||
|
||||
unleash
|
||||
.start({
|
||||
// ... Other options emitted for brevity
|
||||
// highlight-next-line
|
||||
enableOAS: true,
|
||||
})
|
||||
.then((unleash) => {
|
||||
console.log(
|
||||
`Unleash started on http://localhost:${unleash.app.get('port')}`,
|
||||
);
|
||||
});
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
|
||||
<TabItem value="proxy" label="Unleash proxy">
|
||||
|
||||
```js title="Enable OpenAPI for the Unleash proxy via configuration"
|
||||
const port = 3000;
|
||||
|
||||
const { createApp } = require('@unleash/proxy');
|
||||
|
||||
const app = createApp({
|
||||
// ... Other options elided for brevity
|
||||
// highlight-next-line
|
||||
enableOAS: true,
|
||||
});
|
||||
|
||||
app.listen(port, () =>
|
||||
console.log(`Unleash Proxy listening on http://localhost:${port}/proxy`),
|
||||
);
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
|
||||
</Tabs>
|
||||
@ -1,35 +0,0 @@
|
||||
---
|
||||
title: How to use the Admin API
|
||||
---
|
||||
|
||||
This guide explains the steps required to using the Admin API.
|
||||
|
||||
## Create API token
|
||||
|
||||
First, you'll need to create a [personal access token](/reference/api-tokens-and-client-keys.mdx#personal-access-tokens).
|
||||
|
||||
Please note that it may take up to 60 seconds for the new key to propagate to all Unleash instances due to eager caching.
|
||||
|
||||
:::note
|
||||
|
||||
If you need an API token to use in a client SDK you should create a client token instead, as these have fewer access rights.
|
||||
|
||||
:::
|
||||
|
||||
## Use Admin API
|
||||
|
||||
Now that you have an access token with admin privileges, you can use it to make changes in your Unleash instance.
|
||||
|
||||
In the example below we will use the [Unleash Admin API](/reference/api/legacy/unleash/admin/features.md) to enable the `checkout-flow` feature flag in `development` using curl.
|
||||
|
||||
```sh
|
||||
curl -X POST -H "Content-Type: application/json" \
|
||||
-H "Authorization: <your-token>" \
|
||||
https://app.unleash-hosted.com/docs-demo/api/admin/projects/docs-project/features/checkout-flow/environments/development/on
|
||||
```
|
||||
|
||||
We have now enabled the feature flag. We can also verify that it was actually changed by the API user by navigating to [Event Log](/reference/events#event-log) and filtering events for this feature flag.
|
||||
|
||||
|
||||
|
||||
You can find the full documentation on everything the Unleash API supports in the [Unleash API documentation](/reference/api/legacy/unleash/admin/features.md).
|
||||
@ -82,7 +82,7 @@ This table describes all the properties on the impression events:
|
||||
|
||||
Impression data is strictly an **opt-in** feature and must be enabled on a **per-flag basis**. You can enable and disable it both when you create a flag and when you edit a flag.
|
||||
|
||||
You can enable impression data via the impression data flag in the admin UI's flag creation form. You can also go via the [the API, using the `impressionData` option](/reference/api/legacy/unleash/admin/features-v2#create-toggle). For more detailed instructions, see [the section on enabling impression data in the how-to guide for capturing impression data](../how-to/how-to-capture-impression-data#step-1).
|
||||
You can enable impression data via the impression data flag in the admin UI's flag creation form. You can also go via the [the API, using the `impressionData` option](/reference/api/legacy/unleash/admin/features-v2#create-toggle). For more detailed instructions, see [the section on enabling impression data in the how-to guide for capturing impression data](/feature-flag-tutorials/use-cases/how-to-capture-impression-data).
|
||||
|
||||
|
||||
|
||||
|
||||
@ -46,7 +46,7 @@ In version 4 we improved the User Management and made it available for Unleash O
|
||||
|
||||
In version 4 we improved the API Access and made it available for Unleash Open-Source and Unleash Enterprise. Starting from Unleash v4 we require all SDKs to use an access token in order to connect to Unleash.
|
||||
|
||||
[Read more](../how-to/how-to-use-the-admin-api)
|
||||
[Read more](../api-overview#admin-api)
|
||||
|
||||
### Custom stickiness {#custom-stickiness}
|
||||
|
||||
|
||||
@ -469,10 +469,6 @@ class="header-github-link"
|
||||
from: '/reference/event-types',
|
||||
to: '/reference/events',
|
||||
},
|
||||
{
|
||||
from: '/advanced/api_access',
|
||||
to: '/how-to/how-to-use-the-admin-api',
|
||||
},
|
||||
{
|
||||
from: '/advanced/archived_toggles',
|
||||
to: '/reference/feature-toggles',
|
||||
|
||||
@ -130,6 +130,11 @@ const sidebars: SidebarsConfig = {
|
||||
label: 'Scaling Unleash',
|
||||
id: 'feature-flag-tutorials/use-cases/scaling-unleash',
|
||||
},
|
||||
{
|
||||
type: 'doc',
|
||||
label: 'Impression Data for Analytics',
|
||||
id: 'feature-flag-tutorials/use-cases/how-to-capture-impression-data',
|
||||
},
|
||||
],
|
||||
},
|
||||
{
|
||||
@ -665,21 +670,6 @@ const sidebars: SidebarsConfig = {
|
||||
slug: '/how-to',
|
||||
},
|
||||
items: [
|
||||
{
|
||||
label: 'Unleash API guides',
|
||||
type: 'category',
|
||||
link: {
|
||||
type: 'generated-index',
|
||||
title: 'How-to: Unleash API',
|
||||
description:
|
||||
'Learn how to work with the Unleash API',
|
||||
slug: '/how-to/api',
|
||||
},
|
||||
items: [
|
||||
'how-to/how-to-use-the-admin-api',
|
||||
'how-to/how-to-enable-openapi',
|
||||
],
|
||||
},
|
||||
{
|
||||
label: 'Feature flags, strategies, context',
|
||||
type: 'category',
|
||||
@ -691,7 +681,6 @@ const sidebars: SidebarsConfig = {
|
||||
slug: '/how-to/misc',
|
||||
},
|
||||
items: [
|
||||
'how-to/how-to-capture-impression-data',
|
||||
'how-to/how-to-create-feature-toggles',
|
||||
'how-to/how-to-create-and-display-banners',
|
||||
'how-to/how-to-schedule-feature-releases',
|
||||
|
||||
@ -91,11 +91,6 @@
|
||||
"destination": "/api-overview",
|
||||
"permanent": true
|
||||
},
|
||||
{
|
||||
"source": "/advanced/api_access",
|
||||
"destination": "/how-to/how-to-use-the-admin-api",
|
||||
"permanent": true
|
||||
},
|
||||
{
|
||||
"source": "/advanced/archived_toggles",
|
||||
"destination": "/reference/feature-toggles#archive-a-feature-toggle",
|
||||
@ -686,6 +681,16 @@
|
||||
"destination": "/contributing/developer-guide",
|
||||
"permanent": true
|
||||
},
|
||||
{
|
||||
"source": "/how-to/how-to-capture-impression-data",
|
||||
"destination": "/feature-flag-tutorials/use-cases/how-to-capture-impression-data",
|
||||
"permanent": true
|
||||
},
|
||||
{
|
||||
"source": "/how-to/how-to-use-the-admin-api",
|
||||
"destination": "/api-overview#admin-api",
|
||||
"permanent": true
|
||||
},
|
||||
{
|
||||
"source": "/tutorials/unleash-overview",
|
||||
"destination": "/understanding-unleash/unleash-overview",
|
||||
@ -701,6 +706,16 @@
|
||||
"destination": "/understanding-unleash/managing-constraints",
|
||||
"permanent": true
|
||||
},
|
||||
{
|
||||
"source": "/how-to/how-to-enable-openapi",
|
||||
"destination": "/api-overview",
|
||||
"permanent": true
|
||||
},
|
||||
{
|
||||
"source": "/how-to/api",
|
||||
"destination": "/api-overview",
|
||||
"permanent": true
|
||||
},
|
||||
{
|
||||
"source": "/topics/managing-constraints",
|
||||
"destination": "/understanding-unleash/managing-constraints",
|
||||
|
||||
Loading…
Reference in New Issue
Block a user