From 0c9c573d1adb50feb2a7414ec78a8fbb6ea14c59 Mon Sep 17 00:00:00 2001 From: melindafekete Date: Wed, 14 May 2025 12:25:41 +0200 Subject: [PATCH] Remove Enable OpernAPI and how to use Admin API --- .../common/ApiTokenTable/ApiTokenTable.tsx | 2 +- .../ProjectAccessAssign.tsx | 2 +- website/docs/api-overview.mdx | 54 ++++++++ .../how-to-capture-impression-data.mdx | 17 +-- .../use-cases/security-compliance.md | 2 +- .../user-management-access-controls.md | 2 +- website/docs/how-to/how-to-enable-openapi.mdx | 125 ------------------ .../docs/how-to/how-to-use-the-admin-api.md | 35 ----- website/docs/reference/impression-data.md | 2 +- website/docs/reference/whats-new-v4.md | 2 +- website/docusaurus.config.ts | 4 - website/sidebars.ts | 21 +-- website/vercel.json | 25 +++- 13 files changed, 92 insertions(+), 201 deletions(-) rename website/docs/{how-to => feature-flag-tutorials/use-cases}/how-to-capture-impression-data.mdx (79%) delete mode 100644 website/docs/how-to/how-to-enable-openapi.mdx delete mode 100644 website/docs/how-to/how-to-use-the-admin-api.md diff --git a/frontend/src/component/common/ApiTokenTable/ApiTokenTable.tsx b/frontend/src/component/common/ApiTokenTable/ApiTokenTable.tsx index edb852a1e3..9c50cdaa0a 100644 --- a/frontend/src/component/common/ApiTokenTable/ApiTokenTable.tsx +++ b/frontend/src/component/common/ApiTokenTable/ApiTokenTable.tsx @@ -86,7 +86,7 @@ export const ApiTokenTable = ({ {'No tokens available. Read '} diff --git a/frontend/src/component/project/ProjectAccess/ProjectAccessAssign/ProjectAccessAssign.tsx b/frontend/src/component/project/ProjectAccess/ProjectAccessAssign/ProjectAccessAssign.tsx index f572c9d019..30c4024668 100644 --- a/frontend/src/component/project/ProjectAccess/ProjectAccessAssign/ProjectAccessAssign.tsx +++ b/frontend/src/component/project/ProjectAccess/ProjectAccessAssign/ProjectAccessAssign.tsx @@ -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} > diff --git a/website/docs/api-overview.mdx b/website/docs/api-overview.mdx index 7a84ea822c..bb3721d875 100644 --- a/website/docs/api-overview.mdx +++ b/website/docs/api-overview.mdx @@ -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: " \ + 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. + +![Feature flag events showing that it was last updated by "admin-api".](/img/api_access_history.png) + +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. diff --git a/website/docs/how-to/how-to-capture-impression-data.mdx b/website/docs/feature-flag-tutorials/use-cases/how-to-capture-impression-data.mdx similarity index 79% rename from website/docs/how-to/how-to-capture-impression-data.mdx rename to website/docs/feature-flag-tutorials/use-cases/how-to-capture-impression-data.mdx index 0341844fc8..d7ec5d3fcb 100644 --- a/website/docs/how-to/how-to-capture-impression-data.mdx +++ b/website/docs/feature-flag-tutorials/use-cases/how-to-capture-impression-data.mdx @@ -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. ``). 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. diff --git a/website/docs/feature-flag-tutorials/use-cases/security-compliance.md b/website/docs/feature-flag-tutorials/use-cases/security-compliance.md index 343ad2f908..3eaa7e65e7 100644 --- a/website/docs/feature-flag-tutorials/use-cases/security-compliance.md +++ b/website/docs/feature-flag-tutorials/use-cases/security-compliance.md @@ -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. ![The diagram showing the relationship between root roles and project roles in Unleash.](/img/root-and-project-roles-comparison.jpg) diff --git a/website/docs/feature-flag-tutorials/use-cases/user-management-access-controls.md b/website/docs/feature-flag-tutorials/use-cases/user-management-access-controls.md index d90240ecfe..6113c9058b 100644 --- a/website/docs/feature-flag-tutorials/use-cases/user-management-access-controls.md +++ b/website/docs/feature-flag-tutorials/use-cases/user-management-access-controls.md @@ -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: diff --git a/website/docs/how-to/how-to-enable-openapi.mdx b/website/docs/how-to/how-to-enable-openapi.mdx deleted file mode 100644 index 11c6bf177a..0000000000 --- a/website/docs/how-to/how-to-enable-openapi.mdx +++ /dev/null @@ -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. - - - - - -```bash title="Enable OpenAPI via an environment variable" -export ENABLE_OAS=true -``` - - - - - -```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 -``` - - - - - -```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 -``` - - - - - -### 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). - - - - - -```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')}`, - ); - }); -``` - - - - - -```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`), -); -``` - - - - diff --git a/website/docs/how-to/how-to-use-the-admin-api.md b/website/docs/how-to/how-to-use-the-admin-api.md deleted file mode 100644 index e4a001b577..0000000000 --- a/website/docs/how-to/how-to-use-the-admin-api.md +++ /dev/null @@ -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: " \ - 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. - -![Feature flag events showing that it was last updated by "admin-api".](/img/api_access_history.png) - -You can find the full documentation on everything the Unleash API supports in the [Unleash API documentation](/reference/api/legacy/unleash/admin/features.md). diff --git a/website/docs/reference/impression-data.md b/website/docs/reference/impression-data.md index 7dd3833d28..e604e3a1ed 100644 --- a/website/docs/reference/impression-data.md +++ b/website/docs/reference/impression-data.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). ![A feature flag creation form. At the end of the form is a heading that says "Impression data", a short paragraph that describes the feature, and a flag to opt in or out of it.](/img/create_feat_impression.png) diff --git a/website/docs/reference/whats-new-v4.md b/website/docs/reference/whats-new-v4.md index 27a8340f2c..ad8563c85e 100644 --- a/website/docs/reference/whats-new-v4.md +++ b/website/docs/reference/whats-new-v4.md @@ -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} diff --git a/website/docusaurus.config.ts b/website/docusaurus.config.ts index 36873c7905..fb0c657cc0 100644 --- a/website/docusaurus.config.ts +++ b/website/docusaurus.config.ts @@ -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', diff --git a/website/sidebars.ts b/website/sidebars.ts index 4af90d4652..0269599105 100644 --- a/website/sidebars.ts +++ b/website/sidebars.ts @@ -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', diff --git a/website/vercel.json b/website/vercel.json index 931c8031be..b43cdf868c 100644 --- a/website/vercel.json +++ b/website/vercel.json @@ -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",