feat: add client side sdk docs

flipt-io · Dec 14, 2023 · 63984dd · 63984dd
1 parent fa279d2
commit 63984dd
Show file tree

Hide file tree

Showing 7 changed files with 151 additions and 22 deletions.
diff --git a/integration/client.mdx b/integration/client.mdx
@@ -0,0 +1,65 @@
+---
+title: Client-Side SDKs
+description: An overview of the client-side SDKs available for integrating with Flipt.
+---
+
+<Info>
+  Not sure which SDK to use? Check out our [Integration
+  Overview](/integration/overview) documentation.
+</Info>
+
+For a more detailed overview of how the client-side SDKs work, check out our announcement blog post: [Client-Side SDKs for Flipt](https://www.flipt.io/blog/new-client-side-evaluation).
+
+## Overview
+
+Flipt provides a number of client-side SDKs to help you integrate with Flipt in your application. The SDKs are available in a number of languages:
+
+<CardGroup cols={2}>
+  <Card
+    title="Node/TypeScript"
+    href="https://github.com/flipt-io/flipt-client-sdks/tree/main/flipt-client-node"
+    icon="node"
+    color="#68a063"
+  >
+    Evaluate flags client-side in your Node applications
+  </Card>
+  <Card
+    href="https://github.com/flipt-io/flipt-client-sdks/tree/main/flipt-client-python"
+    title="Python"
+    icon="python"
+    color="#4c8abe"
+  >
+    Evaluate flags client-side in your Python applications
+  </Card>
+  <Card
+    href="https://github.com/flipt-io/flipt-client-sdks/tree/main/flipt-client-go"
+    title="Go"
+    icon="golang"
+    color="#00add8"
+  >
+    Evaluate flags client-side in your Go applications
+  </Card>
+  <Card
+    href="https://github.com/flipt-io/flipt-client-sdks/tree/main/flipt-client-ruby"
+    title="Ruby"
+    icon="gem"
+    color="#cd412b"
+  >
+    Evaluate flags client-side in your Ruby applications
+  </Card>
+  <Card
+    href="https://github.com/flipt-io/flipt-client-sdks/issues/new"
+    title="Request a Client"
+    icon="github"
+    color="#000000"
+  >
+    > Need a client in another language? Let us know!
+  </Card>
+</CardGroup>
+
+<Warning>
+  Our client-side SDKs are currently in **beta**.
+
+We're actively working on improving them and adding more languages. If you have any feedback, feature or language requests, please let us know by opening an issue in our [GitHub repository](https://github.com/flipt-io/flipt-client-sdks).
+
+</Warning>
diff --git a/integration/openfeature.mdx b/integration/openfeature.mdx
@@ -22,15 +22,21 @@ OpenFeature allows you to use the same feature flagging API across multiple feat
 
 OpenFeature is a CNCF Sandbox project. You can learn more about OpenFeature on the [OpenFeature website](https://openfeature.dev/).
 
-## Flipt OpenFeature Providers
+## 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.
 
+<Note>
+  We currently only provide server-side OpenFeature providers. Once the
+  OpenFeature client-side specification is finalized, we will provide
+  client-side OpenFeature providers as well.
+</Note>
+
 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:
+We currently provide the following OpenFeature server-side providers:
 
 <CardGroup cols={2}>
   <Card

diff --git a/integration/overview.mdx b/integration/overview.mdx
@@ -3,33 +3,67 @@ 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.
+<Info>
+  To learn how to install and run Flipt, see the [Installation](/installation)
+  documentation.
+</Info>
 
-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.
+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 for evaluating your feature flags.
 
-You have two options to communicate with the Flipt server:
+There two main ways to perform evaluation of feature flags with Flipt:
+
+1. [Server-Side Evaluation](#server-side-evaluation)
+1. [Client-Side Evaluation](#client-side-evaluation)
+
+## Server-Side Evaluation
+
+Server-side evaluation is the most common way to evaluate feature flags. This is where your application makes a request to Flipt to evaluate a feature flag and Flipt responds with the result of the evaluation.
+
+Flipt exposes two different APIs for performing server-side evaluation:
 
 1. [REST API](#rest-api)
 1. [GRPC API](#grpc-api)
 
-We've also developed several clients in various languages for easier integration.
+The choice of which API to use is up to you. Both APIs are fully supported and are functionally equivalent. The REST API is easier to get started with, but the GRPC API is more performant.
 
-## REST API
+### 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.
+Flipt 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 Flipt REST API can also be used with any language that can make HTTP requests. This means that you don't need have to use one of our official 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.
+See all official REST SDKs as well as how to generate your own in the the [REST SDK](/integration/server/rest) section.
 
-## GRPC API
+### 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.
 
+<Note>GRPC requires HTTP/2 in your environment.</Note>
+
 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.
+See all official GRPC SDKs as well as how to generate your own in the the [GRPC SDK](/integration/server/grpc) section.
+
+## Client-Side Evaluation
+
+Client-side evaluation is another way Flipt supports evaluating feature flags. This is where your application has a local copy of the feature flag rules and evaluates the feature flag locally.
+
+<Warning>
+  Our client-side SDKs are currently in **beta**.
+
+We're actively working on improving them and adding more languages. If you have any feedback, feature or language requests, please let us know by opening an issue in our [GitHub repository](https://github.com/flipt-io/flipt-client-sdks).
+
+</Warning>
+
+Client-side evaluation is much more performant than server-side evaluation, but it comes with some tradeoffs. The main tradeoff is that you need to keep your feature flag rules in sync with Flipt. This means that you will need to periodically fetch the feature flag rules from Flipt and update your local copy. Our client-side SDKs provide a way to do this automatically.
+
+Reasons for using client side evaluation include:
+
+- Your application is running in an environment where it cannot make requests to Flipt for each feature flag evaluation (for example a mobile application)
+- You want to reduce the number of requests your application makes to Flipt for feature flag evaluations
+- You want to reduce the latency of feature flag evaluations
+
+See all official client-side SDKs in the the [Client-Side SDKs](/integration/client) section.
diff --git a/integration/grpc.mdx → integration/server/grpc.mdx b/integration/grpc.mdx → integration/server/grpc.mdx
@@ -1,11 +1,16 @@
 ---
 title: GRPC SDKs
-description: An overview of the GRPC SDKs available for integrating with Flipt.
+description: An overview of the GRPC server-side SDKs available for integrating with Flipt.
 ---
 
-## Official Clients
+<Info>
+  Not sure which SDK to use? Check out our [Integration
+  Overview](/integration/overview) documentation.
+</Info>
 
-Official Flipt GRPC clients are currently available for the following languages:
+## Overview
+
+For server-side applications, Flipt provides a GRPC API for evaluating flags. The GRPC API SDKs are available in the following languages:
 
 <CardGroup cols={2}>
   <Card

diff --git a/integration/rest.mdx → integration/server/rest.mdx b/integration/rest.mdx → integration/server/rest.mdx
@@ -1,11 +1,16 @@
 ---
 title: REST SDKs
-description: An overview of the REST SDKs available for integrating with Flipt.
+description: An overview of the REST server-side SDKs available for integrating with Flipt.
 ---
 
-## Official Clients
+<Info>
+  Not sure which SDK to use? Check out our [Integration
+  Overview](/integration/overview) documentation.
+</Info>
 
-Official Flipt REST clients are currently available in the following languages:
+## Overview
+
+For server-side applications, Flipt provides a REST API for evaluating flags. The REST API SDKs are available in the following languages:
 
 <CardGroup cols={2}>
   <Card

diff --git a/mint.json b/mint.json
@@ -84,8 +84,14 @@
       "group": "Integration",
       "pages": [
         "integration/overview",
-        "integration/rest",
-        "integration/grpc",
+        {
+          "group": "Server-Side SDKs",
+          "pages": [
+            "integration/server/rest",
+            "integration/server/grpc"
+          ]
+        },
+        "integration/client",
         "integration/openfeature",
         "integration/examples"
       ]
@@ -289,6 +295,14 @@
     {
       "source": "/installation",
       "destination": "/self-hosted/overview"
+    },
+    {
+      "source": "/integration/rest",
+      "destination": "/integration/server/rest"
+    },
+    { 
+      "source": "/integration/grpc",
+      "destination": "/integration/server/grpc"
     }
   ],
   "footerSocials": {

diff --git a/reference/overview.mdx b/reference/overview.mdx
@@ -12,7 +12,7 @@ The latest version of the REST API is fully documented using the [OpenAPI v3 spe
 
 ## SDKs
 
-We're adding new SDKs all the time. To see the current list of official REST SDKs, head to the [REST SDKs](/integration/rest) documentation.
+We're adding new SDKs all the time. To see the current list of official REST SDKs, head to the [REST SDKs](/integration/server/rest) documentation.
 
 ## Backward Compatibility
-Original file line number
+Diff line change
@@ Expand Up @@
     ## SDKs
-    We're adding new SDKs all the time. To see the current list of official REST SDKs, head to the [REST SDKs](/integration/rest) documentation.
+    We're adding new SDKs all the time. To see the current list of official REST SDKs, head to the [REST SDKs](/integration/server/rest) documentation.
     ## Backward Compatibility
@@ Expand Down @@