From 11ddd2026c53104febd8cb3803c20233f2d4b032 Mon Sep 17 00:00:00 2001 From: Mark Phelps <209477+markphelps@users.noreply.github.com> Date: Wed, 27 Sep 2023 12:10:34 -0400 Subject: [PATCH 1/5] feat: change up docs, add more indepth integration doc --- integration.mdx | 189 --------------------------------------- integration/examples.mdx | 89 ++++++++++++++++++ integration/grpc.mdx | 87 ++++++++++++++++++ integration/overview.mdx | 35 ++++++++ integration/rest.mdx | 74 +++++++++++++++ mint.json | 23 +++-- 6 files changed, 303 insertions(+), 194 deletions(-) delete mode 100644 integration.mdx create mode 100644 integration/examples.mdx create mode 100644 integration/grpc.mdx create mode 100644 integration/overview.mdx create mode 100644 integration/rest.mdx diff --git a/integration.mdx b/integration.mdx deleted file mode 100644 index abe060b..0000000 --- a/integration.mdx +++ /dev/null @@ -1,189 +0,0 @@ ---- -title: Integration -description: This document describes how to integrate Flipt in your existing applications. ---- - -To learn how to install and run Flipt, see the [Installation](/installation) -documentation. - -Once you have the Flipt server up and running within your infrastructure, the -next step is to integrate the Flipt client(s) with your applications that you -would like to be able to use with Flipt. - -You have two options to communicate with the Flipt server: - -1. REST API -1. GRPC API - -We've also developed several clients in various languages for easier integration. - -## REST API - -Flipt also comes equipped with a fully functional REST API. The Flipt UI is completely backed by this same API. This means that anything that can be done in the Flipt UI can also be done via the REST API. - -The Flipt REST API can also be used with any language that can make HTTP requests. This means that you don't need to use one of the above GRPC clients to integrate your application with Flipt. - -The latest version of the REST API is fully documented using the [OpenAPI v3 specification](https://github.com/flipt-io/flipt-openapi) as well as the above [API Reference](/reference/overview). - -## REST Clients - -### Official Clients - -Official Flipt REST clients are currently available in the following languages: - - - - Evaluate flags in your Node applications - - - Evaluate flags in your Python applications - - - Evaluate flags in your Go applications - - - Evaluate flags in your Rust applications - - - Evaluate flags in your Java applications - - - > Need a client in another language? Let us know! - - - -### Generate - -You can use [openapi-generator](https://openapi-generator.tech/) to generate client code in your preferred language from the [Flipt OpenAPI v3 specification](https://github.com/flipt-io/flipt-openapi). - -While generating clients is outside of the scope of this documentation, an example of generating a Java client with the `openapi-generator` is below. - -**Java Example** - -1. Install [`openapi-generator`](https://openapi-generator.tech/docs/installation) -2. Generate using `openapi-generator-cli` to desired location: - -``` -openapi-generator generate -i openapi.yml -g java -o /tmp/flipt/java -``` - -## GRPC Clients - -Since Flipt is a [GRPC](https://grpc.io/) enabled application, you can use a -generated GRPC client for your language of choice. - -An example [Go application](https://github.com/flipt-io/flipt/tree/main/examples/basic) is available, showing how you would -integrate with Flipt using the Go GRPC client. - -### Official Clients - -Official Flipt GRPC clients are currently available for the following languages: - - - - Evaluate flags in your Go applications with GRPC - - - Evaluate flags in your Ruby applications with GRPC - - - Evaluate flags in your .NET applications with GRPC - - - > Need a client in another language? Let us know! - - - -If your language isn't listed, please see the section below on how to generate -a native GRPC client manually. If you choose to open-source this client, please -submit a pull request so that we can add it to the docs. - -### Generate - -If a GRPC client in your language isn't available for download, you can easily -generate it yourself using the existing -[protobuf definition](https://github.com/flipt-io/flipt/blob/main/rpc/flipt/flipt.proto). -The [GRPC documentation](https://grpc.io/docs/) has extensive examples of how to -generate GRPC clients in each supported language. - - - GRPC generates both client implementation and server interfaces. To use Flipt - you only need the GRPC client implementation and can ignore the server code as - this is implemented by Flipt itself. - - -Below are two examples of how to generate Flipt clients in both Go and Ruby. - -**Go Example** - -1. Follow the [setup instructions](https://grpc.io/docs/quickstart/go/) on the GRPC website. -2. Generate using protoc to desired location: - -```console -protoc -I ./rpc --go_out=plugins=grpc:/tmp/flipt/go ./rpc/flipt.proto -cd /tmp/flipt/go/flipt -ls -flipt.pb.go flipt_pb.rb flipt_services_pb. -``` - -**Ruby Example** - -1. Follow the [setup instructions](https://grpc.io/docs/quickstart/ruby/) on the GRPC website. -2. Generate using protoc to the desired location: - -```console -grpc_tools_ruby_protoc -I ./rpc --ruby_out=/tmp/flipt/ruby --grpc_out=/tmp/flipt/ruby ./rpc/flipt.proto -cd /tmp/flipt/ruby -ls -flipt_pb.rb flipt_services_pb.rb -``` diff --git a/integration/examples.mdx b/integration/examples.mdx new file mode 100644 index 0000000..665a5a0 --- /dev/null +++ b/integration/examples.mdx @@ -0,0 +1,89 @@ +--- +title: Examples +description: Examples on how Flipt can be integrated into various applications, frameworks, and tools. +--- + +All of our examples are available on [GitHub](https://github.com/flipt-io/flipt/tree/main/examples). Here are some hand-picked examples to get you started. + +## Applications + + + + How to integrate Flipt into your Go applications with GRPC + + + How to integrate Flipt into your Next.js applications using both server-side + and client-side rendering + + + +## Configuration + + + + How to setup OIDC authentication with Flipt + + + Configure Flipt to use a PostgreSQL, MySQL or CockroachDB databases + + + Configure Flipt to use an external Redis cache for improved performance + + + +## Tooling + + + + Integrate Flipt with OpenTelemetry to trace requests with feature flag + evaluations + + + Integrate Flipt with Prometheus and Grafana to collect metrics on your + feature flag usage + + + Setup audit logging and webhooks for Flipt to track changes within the + system + + diff --git a/integration/grpc.mdx b/integration/grpc.mdx new file mode 100644 index 0000000..1a38009 --- /dev/null +++ b/integration/grpc.mdx @@ -0,0 +1,87 @@ +--- +title: GRPC SDKs +description: An overview of the GRPC SDKs available for integrating with Flipt. +--- + +## Official Clients + +Official Flipt GRPC clients are currently available for the following languages: + + + + Evaluate flags in your Go applications with GRPC + + + Evaluate flags in your Ruby applications with GRPC + + + Evaluate flags in your .NET applications with GRPC + + + > Need a client in another language? Let us know! + + + +If your language isn't listed, please see the section below on how to generate +a native GRPC client manually. If you choose to open-source this client, please +submit a pull request so that we can add it to the docs. + +## Generate + +If a GRPC client in your language isn't available for download, you can easily +generate it yourself using the existing +[protobuf definition](https://github.com/flipt-io/flipt/blob/main/rpc/flipt/flipt.proto). +The [GRPC documentation](https://grpc.io/docs/) has extensive examples of how to +generate GRPC clients in each supported language. + + + GRPC generates both client implementation and server interfaces. To use Flipt + you only need the GRPC client implementation and can ignore the server code as + this is implemented by Flipt itself. + + +Below are two examples of how to generate Flipt clients in both Go and Ruby. + +**Go Example** + +1. Follow the [setup instructions](https://grpc.io/docs/quickstart/go/) on the GRPC website. +2. Generate using protoc to desired location: + +```console +protoc -I ./rpc --go_out=plugins=grpc:/tmp/flipt/go ./rpc/flipt.proto +cd /tmp/flipt/go/flipt +ls +flipt.pb.go flipt_pb.rb flipt_services_pb. +``` + +**Ruby Example** + +1. Follow the [setup instructions](https://grpc.io/docs/quickstart/ruby/) on the GRPC website. +2. Generate using protoc to the desired location: + +```console +grpc_tools_ruby_protoc -I ./rpc --ruby_out=/tmp/flipt/ruby --grpc_out=/tmp/flipt/ruby ./rpc/flipt.proto +cd /tmp/flipt/ruby +ls +flipt_pb.rb flipt_services_pb.rb +``` diff --git a/integration/overview.mdx b/integration/overview.mdx new file mode 100644 index 0000000..fce67b7 --- /dev/null +++ b/integration/overview.mdx @@ -0,0 +1,35 @@ +--- +title: Overview +description: This document describes how to integrate Flipt in your existing applications. +--- + +To learn how to install and run Flipt, see the [Installation](/installation) +documentation. + +Once you have the Flipt server up and running within your infrastructure or local development environment, the next step is to integrate the Flipt client(s) with your applications. + +You have two options to communicate with the Flipt server: + +1. [REST API](#rest-api) +1. [GRPC API](#grpc-api) + +We've also developed several clients in various languages for easier integration. + +## REST API + +Flipt also comes equipped with a fully functional REST API. The Flipt UI is completely backed by this same API. This means that anything that can be done in the Flipt UI can also be done via the REST API. + +The Flipt REST API can also be used with any language that can make HTTP requests. This means that you don't need to use one of the above GRPC clients to integrate your application with Flipt. + +The latest version of the REST API is fully documented using the [OpenAPI v3 specification](https://github.com/flipt-io/flipt-openapi) as well as the above [API Reference](/reference/overview). + +See all official REST clients as well as how to generate your own in the the [REST SDK](/integration/rest) section. + +## GRPC API + +Since Flipt is a [GRPC](https://grpc.io/) enabled application, you can connect to it using the GRPC protocol. This means that you can use any language that has a GRPC client implementation to integrate with Flipt. + +An example [Go application](https://github.com/flipt-io/flipt/tree/main/examples/basic) is available, showing how you would +integrate with Flipt using the Go GRPC client. + +See all official GRPC clients as well as how to generate your own in the the [GRPC SDK](/integration/grpc) section. diff --git a/integration/rest.mdx b/integration/rest.mdx new file mode 100644 index 0000000..035e2c5 --- /dev/null +++ b/integration/rest.mdx @@ -0,0 +1,74 @@ +--- +title: REST SDKs +description: An overview of the REST SDKs available for integrating with Flipt. +--- + +## Official Clients + +Official Flipt REST clients are currently available in the following languages: + + + + Evaluate flags in your Node applications + + + Evaluate flags in your Python applications + + + Evaluate flags in your Go applications + + + Evaluate flags in your Rust applications + + + Evaluate flags in your Java applications + + + > Need a client in another language? Let us know! + + + +## Generate + +You can use [openapi-generator](https://openapi-generator.tech/) to generate client code in your preferred language from the [Flipt OpenAPI v3 specification](https://github.com/flipt-io/flipt-openapi). + +While generating clients is outside of the scope of this documentation, an example of generating a Java client with the `openapi-generator` is below. + +**Java Example** + +1. Install [`openapi-generator`](https://openapi-generator.tech/docs/installation) +2. Generate using `openapi-generator-cli` to desired location: + +``` +openapi-generator generate -i openapi.yml -g java -o /tmp/flipt/java +``` diff --git a/mint.json b/mint.json index 06e3114..a9bd8ae 100644 --- a/mint.json +++ b/mint.json @@ -36,7 +36,7 @@ "anchors": [ { "name": "API Reference", - "icon": "square-terminal", + "icon": "cloud", "url": "reference" }, { @@ -45,20 +45,33 @@ "url": "https://www.flipt.io/blog" }, { - "name": "Community", + "name": "Changelog", + "icon": "timer", + "url": "https://features.flipt.io/changelog" + }, + { + "name": "Discord", "icon": "discord", "url": "https://www.flipt.io/discord" } ], "navigation": [ { - "group": "Home", + "group": "Overview", "pages": [ "introduction", "usecases", "concepts", - "installation", - "integration" + "installation" + ] + }, + { + "group": "Integration", + "pages": [ + "integration/overview", + "integration/rest", + "integration/grpc", + "integration/examples" ] }, { From abfacccf673144d64b434147074a2dd93289f2aa Mon Sep 17 00:00:00 2001 From: Mark Phelps <209477+markphelps@users.noreply.github.com> Date: Wed, 27 Sep 2023 12:42:15 -0400 Subject: [PATCH 2/5] chore: add openfeature section --- images/integration/openfeature-dark.svg | 13 ++++++ images/integration/openfeature-light.svg | 13 ++++++ integration/examples.mdx | 6 +++ integration/openfeature.mdx | 53 ++++++++++++++++++++++++ mint.json | 1 + 5 files changed, 86 insertions(+) create mode 100644 images/integration/openfeature-dark.svg create mode 100644 images/integration/openfeature-light.svg create mode 100644 integration/openfeature.mdx diff --git a/images/integration/openfeature-dark.svg b/images/integration/openfeature-dark.svg new file mode 100644 index 0000000..18388b9 --- /dev/null +++ b/images/integration/openfeature-dark.svg @@ -0,0 +1,13 @@ + + + + + + + + + + + + + \ No newline at end of file diff --git a/images/integration/openfeature-light.svg b/images/integration/openfeature-light.svg new file mode 100644 index 0000000..83ef849 --- /dev/null +++ b/images/integration/openfeature-light.svg @@ -0,0 +1,13 @@ + + + + + + + + + + + + + \ No newline at end of file diff --git a/integration/examples.mdx b/integration/examples.mdx index 665a5a0..6b74195 100644 --- a/integration/examples.mdx +++ b/integration/examples.mdx @@ -7,6 +7,8 @@ All of our examples are available on [GitHub](https://github.com/flipt-io/flipt/ ## Applications +Examples on how to integrate Flipt into various applications and frameworks. + + + + + +[OpenFeature](https://openfeature.dev/) is an open specification that provides a vendor-agnostic, community-driven API for feature flagging that works with your favorite feature flag management tool. + +It is an open standard that allows you to use the same feature flagging API across multiple feature flag management tools. This means that you can switch between feature flag management tools without having to change your code. + +OpenFeature is a CNCF Sandbox project. You can learn more about OpenFeature on the [OpenFeature website](https://openfeature.dev/). + +## Flipt OpenFeature Providers + +As a feature flag management tool, Flipt provides our own OpenFeature integrations (providers). This means that you can use the OpenFeature API with Flipt. + +From the [OpenFeature Specification](https://docs.openfeature.dev/docs/specification/sections/providers): + +> Providers are the "translator" between the flag evaluation calls made in application code, and the flag management system that stores flags and in some cases evaluates flags. + +We currently provide the following OpenFeature providers: + + + + The official Flipt OpenFeature Provider using the OpenFeature Go SDK. + + + The official Flipt OpenFeature Provider using the OpenFeature Java SDK. + + + > Need a client in another language? Let us know! + + diff --git a/mint.json b/mint.json index a9bd8ae..d2da9fd 100644 --- a/mint.json +++ b/mint.json @@ -71,6 +71,7 @@ "integration/overview", "integration/rest", "integration/grpc", + "integration/openfeature", "integration/examples" ] }, From b45b58e51aa12aa6ec8521c4a9d7f5459dcd6ff0 Mon Sep 17 00:00:00 2001 From: Mark Phelps <209477+markphelps@users.noreply.github.com> Date: Wed, 27 Sep 2023 13:08:23 -0400 Subject: [PATCH 3/5] chore: openfeature wording --- integration/openfeature.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/integration/openfeature.mdx b/integration/openfeature.mdx index 0d77a29..49f5bc2 100644 --- a/integration/openfeature.mdx +++ b/integration/openfeature.mdx @@ -16,7 +16,7 @@ description: An overview of OpenFeature and Flipt OpenFeature integrations. [OpenFeature](https://openfeature.dev/) is an open specification that provides a vendor-agnostic, community-driven API for feature flagging that works with your favorite feature flag management tool. -It is an open standard that allows you to use the same feature flagging API across multiple feature flag management tools. This means that you can switch between feature flag management tools without having to change your code. +OpenFeature allows you to use the same feature flagging API across multiple feature flag management tools. This means that you can switch between feature flag management tools without having to change your code. OpenFeature is a CNCF Sandbox project. You can learn more about OpenFeature on the [OpenFeature website](https://openfeature.dev/). From 1e5d369bb20fb466659c97975ac363cffd91718a Mon Sep 17 00:00:00 2001 From: Mark Phelps <209477+markphelps@users.noreply.github.com> Date: Wed, 27 Sep 2023 13:13:48 -0400 Subject: [PATCH 4/5] chore: add nozoom to of image --- integration/openfeature.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/integration/openfeature.mdx b/integration/openfeature.mdx index 49f5bc2..8cd0c5b 100644 --- a/integration/openfeature.mdx +++ b/integration/openfeature.mdx @@ -5,10 +5,12 @@ description: An overview of OpenFeature and Flipt OpenFeature integrations. From 2c7cad372457644003b5d0019cafa48f91ad00b5 Mon Sep 17 00:00:00 2001 From: Mark Phelps <209477+markphelps@users.noreply.github.com> Date: Wed, 27 Sep 2023 13:18:33 -0400 Subject: [PATCH 5/5] chore: update cache icon --- integration/examples.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/integration/examples.mdx b/integration/examples.mdx index 6b74195..7135ccc 100644 --- a/integration/examples.mdx +++ b/integration/examples.mdx @@ -53,7 +53,7 @@ Examples on how to configure Flipt to fit your needs. Configure Flipt to use an external Redis cache for improved performance