From 93eac2699a5cefa98ac9c2558953cfdb0028daf0 Mon Sep 17 00:00:00 2001 From: deleteLater Date: Tue, 27 Jan 2026 19:44:57 +0800 Subject: [PATCH 1/8] added poliing api doc --- pages/sdk/retrieve-feature-flags-with-api.mdx | 42 +++++++++++++++++++ 1 file changed, 42 insertions(+) diff --git a/pages/sdk/retrieve-feature-flags-with-api.mdx b/pages/sdk/retrieve-feature-flags-with-api.mdx index c009394..436c72b 100644 --- a/pages/sdk/retrieve-feature-flags-with-api.mdx +++ b/pages/sdk/retrieve-feature-flags-with-api.mdx @@ -13,6 +13,24 @@ The differences between client side and server side SDKs are: Please note that you need to replace `{Host}` in the API requests with the appropriate host URL for your environment. `{Host}` can be the evaluation server host or the FeatBit Agent host, both of them provides the same API. +## Polling With Timestamp Parameter + +Both APIs support an optional `timestamp` query parameter that enables efficient polling for feature flag updates. When provided, the server will only return flags that have been modified after the specified timestamp. This helps reduce bandwidth and processing overhead by avoiding unnecessary data transfers when flags haven't changed. + +**How it works:** + +1. Make an initial request without the `timestamp` parameter to get all feature flags +2. Store the **max** `timestamp` value from the response +3. In subsequent polling requests, include the stored timestamp as a query parameter: `?timestamp={value}` +4. The server will only return flags modified after that timestamp +5. Update your stored timestamp with the latest value from each response + +**Benefits:** + +* Reduced network bandwidth usage +* Lower server load +* Faster response times when no changes have occurred + ## Client Side For client-side requests, provide the client environment secret in the `Authorization` header. @@ -20,6 +38,7 @@ For client-side requests, provide the client environment secret in the `Authoriz **Request** ```bash +# Initial request (no timestamp) curl -X POST {Host}/api/public/sdk/client/latest-all \ -H 'Content-Type: application/json' \ -H 'Authorization: client-env-secret' \ @@ -37,6 +56,25 @@ curl -X POST {Host}/api/public/sdk/client/latest-all \ } ] }' + +# Subsequent polling request (with timestamp) +curl -X POST '{Host}/api/public/sdk/client/latest-all?timestamp=1712755780494' \ +-H 'Content-Type: application/json' \ +-H 'Authorization: client-env-secret' \ +-d '{ + "keyId": "bot-id", + "name": "bot", + "customizedProperties": [ + { + "name": "level", + "value": "high" + }, + { + "name": "localtion", + "value": "us" + } + ] +}' ``` **Response** @@ -79,7 +117,11 @@ For server-side requests, provide the server environment secret in the `Authoriz **Request** ```bash +# Initial request (no timestamp) curl -H "Authorization: server-env-secret" {Host}/api/public/sdk/server/latest-all + +# Subsequent polling request (with timestamp) +curl -H "Authorization: server-env-secret" '{Host}/api/public/sdk/server/latest-all?timestamp=1712755780494' ``` **Response** From 899f00a6682a8889546596e511bba45ed91a8733 Mon Sep 17 00:00:00 2001 From: deleteLater Date: Tue, 27 Jan 2026 19:58:49 +0800 Subject: [PATCH 2/8] copilot review --- pages/sdk/retrieve-feature-flags-with-api.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/pages/sdk/retrieve-feature-flags-with-api.mdx b/pages/sdk/retrieve-feature-flags-with-api.mdx index 436c72b..ecd8ec2 100644 --- a/pages/sdk/retrieve-feature-flags-with-api.mdx +++ b/pages/sdk/retrieve-feature-flags-with-api.mdx @@ -10,7 +10,7 @@ The differences between client side and server side SDKs are: * Client side SDK relies on the Evaluation Server to evaluate all the flags while Server side SDK evaluates the flags locally -Please note that you need to replace `{Host}` in the API requests with the appropriate host URL for your environment. `{Host}` can be the evaluation server host or the FeatBit Agent host, both of them provides the same API. +Please note that you need to replace `{Host}` in the API requests with the appropriate host URL for your environment. `{Host}` can be the evaluation server host or the FeatBit Agent host, both of them provide the same API. ## Polling With Timestamp Parameter @@ -51,13 +51,13 @@ curl -X POST {Host}/api/public/sdk/client/latest-all \ "value": "high" }, { - "name": "localtion", + "name": "location", "value": "us" } ] }' -# Subsequent polling request (with timestamp) +# Subsequent polling request (with timestamp in milliseconds) curl -X POST '{Host}/api/public/sdk/client/latest-all?timestamp=1712755780494' \ -H 'Content-Type: application/json' \ -H 'Authorization: client-env-secret' \ @@ -70,7 +70,7 @@ curl -X POST '{Host}/api/public/sdk/client/latest-all?timestamp=1712755780494' \ "value": "high" }, { - "name": "localtion", + "name": "location", "value": "us" } ] @@ -120,7 +120,7 @@ For server-side requests, provide the server environment secret in the `Authoriz # Initial request (no timestamp) curl -H "Authorization: server-env-secret" {Host}/api/public/sdk/server/latest-all -# Subsequent polling request (with timestamp) +# Subsequent polling request (with timestamp in milliseconds) curl -H "Authorization: server-env-secret" '{Host}/api/public/sdk/server/latest-all?timestamp=1712755780494' ``` From 95c260c536a68f8bee7724e7d96af3d5a3d1de90 Mon Sep 17 00:00:00 2001 From: deleteLater Date: Wed, 28 Jan 2026 12:54:32 +0800 Subject: [PATCH 3/8] clarify how to get timestamp --- pages/sdk/retrieve-feature-flags-with-api.mdx | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/pages/sdk/retrieve-feature-flags-with-api.mdx b/pages/sdk/retrieve-feature-flags-with-api.mdx index ecd8ec2..a4cde07 100644 --- a/pages/sdk/retrieve-feature-flags-with-api.mdx +++ b/pages/sdk/retrieve-feature-flags-with-api.mdx @@ -7,7 +7,7 @@ The Evaluation Server offers two APIs that allow you to retrieve feature flags f The differences between client side and server side SDKs are: * Client side SDK is for single user but Server side SDK is for multiple users -* Client side SDK relies on the Evaluation Server to evaluate all the flags while Server side SDK evaluates the flags locally +* Client side SDK relies on the Evaluation Server to evaluate all the flags while Server Side SDK evaluates the flags locally Please note that you need to replace `{Host}` in the API requests with the appropriate host URL for your environment. `{Host}` can be the evaluation server host or the FeatBit Agent host, both of them provide the same API. @@ -25,6 +25,11 @@ Both APIs support an optional `timestamp` query parameter that enables efficient 4. The server will only return flags modified after that timestamp 5. Update your stored timestamp with the latest value from each response +**Where to read the timestamp from:** + +* **Client-side requests:** Extract the `timestamp` field from each feature flag object in the `data.featureFlags` array. Take the **maximum** value from all timestamps. +* **Server-side requests:** Extract the `updatedAt` field from all objects in both the `data.featureFlags` and `data.segments` arrays. Find the **latest** among them and convert it to milliseconds. + **Benefits:** * Reduced network bandwidth usage From 603720888551ed8f23ede2f83c34a963c4dac182 Mon Sep 17 00:00:00 2001 From: deleteLater Date: Wed, 28 Jan 2026 13:20:13 +0800 Subject: [PATCH 4/8] enhance clarity for Client-side API and Server-side API --- pages/sdk/retrieve-feature-flags-with-api.mdx | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/pages/sdk/retrieve-feature-flags-with-api.mdx b/pages/sdk/retrieve-feature-flags-with-api.mdx index a4cde07..239a45b 100644 --- a/pages/sdk/retrieve-feature-flags-with-api.mdx +++ b/pages/sdk/retrieve-feature-flags-with-api.mdx @@ -2,12 +2,10 @@ import { Callout } from 'nextra/components' # Retrieve feature flags with API -The Evaluation Server offers two APIs that allow you to retrieve feature flags for both client-side and server-side sdks, specific to the desired environment. +The Evaluation Server offers two APIs that allow us to retrieve feature flags for both client-side and server-side SDKs, specific to the given environment. -The differences between client side and server side SDKs are: - -* Client side SDK is for single user but Server side SDK is for multiple users -* Client side SDK relies on the Evaluation Server to evaluate all the flags while Server Side SDK evaluates the flags locally +* **Client-side API:** For single devices used by individual users. Client-side requests retrieve all **evaluated feature flag values for a specific user**. The server performs all flag evaluations and returns only the results. +* **Server-side API:** For services that handle multiple users. Server-side requests return all **raw feature flags and segments data**. The Server-side SDK then uses this data to evaluate feature flag values locally for each given user. Please note that you need to replace `{Host}` in the API requests with the appropriate host URL for your environment. `{Host}` can be the evaluation server host or the FeatBit Agent host, both of them provide the same API. @@ -38,7 +36,7 @@ Both APIs support an optional `timestamp` query parameter that enables efficient ## Client Side -For client-side requests, provide the client environment secret in the `Authorization` header. +For client-side requests, provide the **client environment secret** in the `Authorization` header. **Request** @@ -117,7 +115,7 @@ curl -X POST '{Host}/api/public/sdk/client/latest-all?timestamp=1712755780494' \ ## Server Side -For server-side requests, provide the server environment secret in the `Authorization` header. +For server-side requests, provide the **server environment secret** in the `Authorization` header. **Request** From 2cd4f066d890afce5ad286634a16db597c2b4c15 Mon Sep 17 00:00:00 2001 From: deleteLater Date: Wed, 28 Jan 2026 16:29:04 +0800 Subject: [PATCH 5/8] typo Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- pages/sdk/retrieve-feature-flags-with-api.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/sdk/retrieve-feature-flags-with-api.mdx b/pages/sdk/retrieve-feature-flags-with-api.mdx index 239a45b..5af40c0 100644 --- a/pages/sdk/retrieve-feature-flags-with-api.mdx +++ b/pages/sdk/retrieve-feature-flags-with-api.mdx @@ -5,7 +5,7 @@ import { Callout } from 'nextra/components' The Evaluation Server offers two APIs that allow us to retrieve feature flags for both client-side and server-side SDKs, specific to the given environment. * **Client-side API:** For single devices used by individual users. Client-side requests retrieve all **evaluated feature flag values for a specific user**. The server performs all flag evaluations and returns only the results. -* **Server-side API:** For services that handle multiple users. Server-side requests return all **raw feature flags and segments data**. The Server-side SDK then uses this data to evaluate feature flag values locally for each given user. +* **Server-side API:** For services that handle multiple users. Server-side requests return all **raw feature flags and segments data**. The server-side SDK then uses this data to evaluate feature flag values locally for each given user. Please note that you need to replace `{Host}` in the API requests with the appropriate host URL for your environment. `{Host}` can be the evaluation server host or the FeatBit Agent host, both of them provide the same API. From a261d9bcd4334b2db7a8382162b4cb7b69e62d4d Mon Sep 17 00:00:00 2001 From: deleteLater Date: Wed, 28 Jan 2026 16:32:00 +0800 Subject: [PATCH 6/8] typo Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- pages/sdk/retrieve-feature-flags-with-api.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/sdk/retrieve-feature-flags-with-api.mdx b/pages/sdk/retrieve-feature-flags-with-api.mdx index 5af40c0..f377d5f 100644 --- a/pages/sdk/retrieve-feature-flags-with-api.mdx +++ b/pages/sdk/retrieve-feature-flags-with-api.mdx @@ -2,7 +2,7 @@ import { Callout } from 'nextra/components' # Retrieve feature flags with API -The Evaluation Server offers two APIs that allow us to retrieve feature flags for both client-side and server-side SDKs, specific to the given environment. +The Evaluation Server offers two APIs that allow you to retrieve feature flags for both client-side and server-side SDKs, specific to the given environment. * **Client-side API:** For single devices used by individual users. Client-side requests retrieve all **evaluated feature flag values for a specific user**. The server performs all flag evaluations and returns only the results. * **Server-side API:** For services that handle multiple users. Server-side requests return all **raw feature flags and segments data**. The server-side SDK then uses this data to evaluate feature flag values locally for each given user. From cae46b3dda658df863052fee195895d8700640d0 Mon Sep 17 00:00:00 2001 From: deleteLater Date: Wed, 28 Jan 2026 16:32:29 +0800 Subject: [PATCH 7/8] remove trailing whitespace Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- pages/sdk/retrieve-feature-flags-with-api.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/sdk/retrieve-feature-flags-with-api.mdx b/pages/sdk/retrieve-feature-flags-with-api.mdx index f377d5f..75a50e6 100644 --- a/pages/sdk/retrieve-feature-flags-with-api.mdx +++ b/pages/sdk/retrieve-feature-flags-with-api.mdx @@ -26,7 +26,7 @@ Both APIs support an optional `timestamp` query parameter that enables efficient **Where to read the timestamp from:** * **Client-side requests:** Extract the `timestamp` field from each feature flag object in the `data.featureFlags` array. Take the **maximum** value from all timestamps. -* **Server-side requests:** Extract the `updatedAt` field from all objects in both the `data.featureFlags` and `data.segments` arrays. Find the **latest** among them and convert it to milliseconds. +* **Server-side requests:** Extract the `updatedAt` field from all objects in both the `data.featureFlags` and `data.segments` arrays. Find the **latest** among them and convert it to milliseconds. **Benefits:** From aec2b28844a76f34fc185a7fa836b5263fae13ff Mon Sep 17 00:00:00 2001 From: deleteLater Date: Wed, 28 Jan 2026 16:33:25 +0800 Subject: [PATCH 8/8] chore --- pages/sdk/retrieve-feature-flags-with-api.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pages/sdk/retrieve-feature-flags-with-api.mdx b/pages/sdk/retrieve-feature-flags-with-api.mdx index 75a50e6..1f56c8f 100644 --- a/pages/sdk/retrieve-feature-flags-with-api.mdx +++ b/pages/sdk/retrieve-feature-flags-with-api.mdx @@ -20,8 +20,8 @@ Both APIs support an optional `timestamp` query parameter that enables efficient 1. Make an initial request without the `timestamp` parameter to get all feature flags 2. Store the **max** `timestamp` value from the response 3. In subsequent polling requests, include the stored timestamp as a query parameter: `?timestamp={value}` -4. The server will only return flags modified after that timestamp -5. Update your stored timestamp with the latest value from each response +4. The server will only return data modified after that timestamp +5. After each response, recompute and update your stored timestamp with the latest value from each response **Where to read the timestamp from:**