From 9d54c094737411838a9c62f30d52a5a57e3e3324 Mon Sep 17 00:00:00 2001 From: Jonathan Norris Date: Fri, 24 Oct 2025 13:54:19 -0400 Subject: [PATCH 1/4] docs: update README.md for publishing on openfeature.dev website Signed-off-by: Jonathan Norris --- README.md | 119 +++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 87 insertions(+), 32 deletions(-) diff --git a/README.md b/README.md index 2246b0c..fe2a3a6 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,5 @@ -# OpenFeature Remote Evaluation Protocol (OFREP) - ---- - + +

@@ -9,49 +7,106 @@

+

OpenFeature Remote Evaluation Protocol (OFREP)

+ ![Protocol version](https://img.shields.io/github/v/release/openfeature/protocol) ## What is OFREP? -**OpenFeature Remote Flag Evaluation Protocol**, is an API specification for feature flagging that allows the use of generic providers to connect to any feature flag management systems that supports the protocol. + + +The **OpenFeature Remote Evaluation Protocol (OFREP)** is an API specification for feature flagging that enables vendor-agnostic communication between applications and flag management systems. It defines a standard API layer between the provider and the flag management system, allowing any OpenSource or commercial system to implement the protocol and be compatible with community-maintained providers. + +### Key Benefits + +- **Vendor Agnostic**: Connect to any OFREP-compliant flag management system without vendor-specific implementations +- **Standardized**: Built on a common OpenAPI specification for consistent integration +- **Flexible**: Works on both client-side and server-side applications +- **Community Maintained**: Generic OFREP providers maintained by the OpenFeature community +- **Simple Migration**: Switch between flag management systems without changing application code + +## How It Works + +OFREP is **a protocol, not a provider**. It defines how to communicate with feature flag management systems and works on top of OpenFeature SDKs by providing standardized providers. + +```mermaid +graph LR + A[Your Application] --> B[OpenFeature SDK] + B --> C[OFREP Provider] + C --> D[OFREP API] + D --> E[Flag Management System] +``` + +1. Your application uses the OpenFeature SDK +2. The OpenFeature SDK uses an OFREP provider +3. The OFREP provider communicates with your flag management system via the standardized OFREP API +4. Your flag management system implements the OFREP specification + +### Server vs Client + +OFREP supports both paradigms defined by OpenFeature: + +#### Server-Side (Dynamic Context) + +- Evaluation happens by calling the OFREP API with context +- No in-process evaluation inside OFREP providers, API request made on every evaluation. +- Context changes frequently (per request, per user) + +#### Client-Side (Static Context) + +- Evaluation happens locally with pre-fetched flag data +- Provider reconciles state using the OFREP API when context changes +- Context represents a single user or session + +## Using OFREP + +### Available Providers + +The OpenFeature community maintains OFREP providers for multiple languages. View the complete list of [OFREP providers in the ecosystem](https://openfeature.dev/ecosystem/?instant_search%5BrefinementList%5D%5Bvendor%5D%5B0%5D=OFREP). -## Goal -The primary goal of the OpenFeature Remote Evaluation Protocol (OFREP) is to establish a standardized, vendor-agnostic communication layer for feature flag evaluation. This protocol aims to decouple applications from specific feature flag vendors, fostering a more flexible and interoperable ecosystem. +### Available Flag Management Systems -At its heart, OFREP defines a standard API layer between the provider and the flag management system, allowing OpenSource and commercial feature flag management systems to implement the protocol and to be compatible with the community maintained providers. It enables out-of-the-box compatibility with any OFREP compliant flag management system, regardless if they have a specific OpenFeature provider implementation or not. +Many flag management systems support OFREP. View the complete list of [OFREP-compliant systems in the ecosystem](https://openfeature.dev/ecosystem/?instant_search%5BrefinementList%5D%5Btype%5D%5B0%5D=OFREP%20API). -If you are building an application that uses feature flags and you don't want to be tied to a specific vendor, you can use the OpenFeature Remote Evaluation Protocol to connect to any flag management system that supports the protocol, without needing to implement a specific provider for it. +## Implementing OFREP -## Things to know -- OFREP is a protocol, not a provider. It defines how to communicate with feature flag management systems. -- OFREP works on top of OpenFeature SDKs, by providing standardized providers that can be used to connect to any OFREP compliant flag management system. -- OFREP works on the client side and the server side. It can be used in web, mobile, and server applications. -- On the servers implementation, OFREP is designed to do evaluation by calling the OFREP API. There is no inprocess evaluation inside the OFREP providers. -- OpenFeature community has built a set of providers that implement the OFREP protocol, allowing you to connect to any OFREP compliant flag management system. +### For Provider Developers -## OFREP Support -The OpenFeature community is maintaining a set of providers implementing the OFREP protocol, you can find the list of available providers in the [ecosystem page](https://openfeature.dev/ecosystem/?instant_search%5BrefinementList%5D%5Bvendor%5D%5B0%5D=OFREP) of the OpenFeature website. +To create an OFREP provider for a new language: -You can also find the list of flag management systems that support the OFREP protocol in the [ecosystem page](https://openfeature.dev/ecosystem/?instant_search%5BrefinementList%5D%5Btype%5D%5B0%5D=OFREP%20API). +1. Review the [server provider guideline](./guideline/dynamic-context-provider.md) or [client provider guideline](./guideline/static-context-provider.md) +2. Implement the provider interface for your SDK +3. Add HTTP client logic to call OFREP endpoints +4. Handle error cases and response codes according to the specification +5. Register your provider in the [OpenFeature ecosystem](https://github.com/open-feature/openfeature.dev/issues) +### For Flag Management System Developers -## Create a provider for OFREP. -If your language is not yet supported and you want to create a provider for OFREP, you can follow the OFREP provider guidelines, they will help you to implement a provider that is compatible with the OpenFeature Remote Evaluation Protocol. +To make your flag management system OFREP-compliant: -- [OFREP Server Provider Guideline](./guideline/dynamic-context-provider.md) -- [OFREP Client Provider Guideline](./guideline/static-context-provider.md) -- [OpenAPI Specification](./service/openapi.yaml) +1. Implement the [OFREP OpenAPI specification](./service/openapi.yaml) +2. Expose OFREP endpoints at `/ofrep/v1/evaluate/...` +3. Support both bulk evaluation (for client-side) and single flag evaluation (for server-side) +4. Test your implementation with existing OFREP providers +5. Register your system in the [OpenFeature ecosystem](https://github.com/open-feature/openfeature.dev/issues) -> [!NOTE] -> After implementing the provider, you can register it in the OpenFeature ecosystem page by [creating an issue](https://github.com/open-feature/openfeature.dev/issues). +## Resources -## Implement OFREP in your flag management system. +- **OpenAPI Specification**: [OFREP OpenAPI Spec](./service/openapi.yaml) +- **Provider Guidelines**: + - [Server Provider Guide](./guideline/dynamic-context-provider.md) + - [Client Provider Guide](./guideline/static-context-provider.md) +- **Ecosystem**: + - [OFREP Providers](https://openfeature.dev/ecosystem/?instant_search%5BrefinementList%5D%5Bvendor%5D%5B0%5D=OFREP) + - [OFREP-Compliant Systems](https://openfeature.dev/ecosystem/?instant_search%5BrefinementList%5D%5Btype%5D%5B0%5D=OFREP%20API) +- **CNCF Slack**: Join [#openfeature-remote-evaluation-protocol](https://cloud-native.slack.com/archives/C066A48LK35) -If you want to implement the OpenFeature Remote Evaluation Protocol in your flag management system, you must support the OpenAPI specification and implement the different endpoints defined. +## Get Involved -- [OpenAPI Specification](./service/openapi.yaml) +OFREP is an open standard maintained by the OpenFeature community. We welcome contributions: -> [!NOTE] -> After implementing the OpenAPI specification, you can register your flag management system in the OpenFeature ecosystem page by [creating an issue](https://github.com/open-feature/openfeature.dev/issues), so users can find it and use it with the OFREP providers. +- **Implement OFREP** in your flag management system +- **Create providers** for additional languages +- **Provide feedback** on the specification +- **Share your experience** using OFREP -## Contribution -If you are interested about the OpenFeature Remote Evaluation Protocol you can join the [`#openfeature-remote-evaluation-protocol`](https://cloud-native.slack.com/archives/C066A48LK35) slack channel on the [CNCF Slack](https://communityinviter.com/apps/cloud-native/cncf). +Join the [`#openfeature-remote-evaluation-protocol`](https://cloud-native.slack.com/archives/C066A48LK35) channel on the [CNCF Slack](https://communityinviter.com/apps/cloud-native/cncf) to get involved. From 81a5e09f48741e38f8347373c7cf36f51530fb14 Mon Sep 17 00:00:00 2001 From: Jonathan Norris Date: Fri, 24 Oct 2025 16:39:00 -0400 Subject: [PATCH 2/4] docs: add x-hide-in-docs at the end Signed-off-by: Jonathan Norris --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index fe2a3a6..755bee3 100644 --- a/README.md +++ b/README.md @@ -89,6 +89,7 @@ To make your flag management system OFREP-compliant: 4. Test your implementation with existing OFREP providers 5. Register your system in the [OpenFeature ecosystem](https://github.com/open-feature/openfeature.dev/issues) + ## Resources - **OpenAPI Specification**: [OFREP OpenAPI Spec](./service/openapi.yaml) @@ -110,3 +111,4 @@ OFREP is an open standard maintained by the OpenFeature community. We welcome co - **Share your experience** using OFREP Join the [`#openfeature-remote-evaluation-protocol`](https://cloud-native.slack.com/archives/C066A48LK35) channel on the [CNCF Slack](https://communityinviter.com/apps/cloud-native/cncf) to get involved. + From 75c87ad6d7aa62ad2dafa5a36c4ee437de2e1d65 Mon Sep 17 00:00:00 2001 From: Jonathan Norris Date: Mon, 27 Oct 2025 11:41:59 -0400 Subject: [PATCH 3/4] docs: README.md cleanup from PR comments Signed-off-by: Jonathan Norris --- README.md | 25 ++++++++++--------------- 1 file changed, 10 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 755bee3..dca0106 100644 --- a/README.md +++ b/README.md @@ -21,8 +21,7 @@ The **OpenFeature Remote Evaluation Protocol (OFREP)** is an API specification f - **Vendor Agnostic**: Connect to any OFREP-compliant flag management system without vendor-specific implementations - **Standardized**: Built on a common OpenAPI specification for consistent integration - **Flexible**: Works on both client-side and server-side applications -- **Community Maintained**: Generic OFREP providers maintained by the OpenFeature community -- **Simple Migration**: Switch between flag management systems without changing application code +- **Community Maintained**: Generic OFREP providers maintained by the OpenFeature project ## How It Works @@ -48,13 +47,13 @@ OFREP supports both paradigms defined by OpenFeature: #### Server-Side (Dynamic Context) - Evaluation happens by calling the OFREP API with context -- No in-process evaluation inside OFREP providers, API request made on every evaluation. -- Context changes frequently (per request, per user) +- API request with evaluation context is made on every evaluation +- Context per evaluation #### Client-Side (Static Context) -- Evaluation happens locally with pre-fetched flag data -- Provider reconciles state using the OFREP API when context changes +- All flags are evaluated in one OFREP API call using a common static context +- Then local flag evaluation happens against the cached static context - Context represents a single user or session ## Using OFREP @@ -65,7 +64,7 @@ The OpenFeature community maintains OFREP providers for multiple languages. View ### Available Flag Management Systems -Many flag management systems support OFREP. View the complete list of [OFREP-compliant systems in the ecosystem](https://openfeature.dev/ecosystem/?instant_search%5BrefinementList%5D%5Btype%5D%5B0%5D=OFREP%20API). +Several flag management systems support OFREP. View the complete list of [OFREP-compliant systems in the ecosystem](https://openfeature.dev/ecosystem/?instant_search%5BrefinementList%5D%5Btype%5D%5B0%5D=OFREP%20API). ## Implementing OFREP @@ -74,20 +73,16 @@ Many flag management systems support OFREP. View the complete list of [OFREP-com To create an OFREP provider for a new language: 1. Review the [server provider guideline](./guideline/dynamic-context-provider.md) or [client provider guideline](./guideline/static-context-provider.md) -2. Implement the provider interface for your SDK -3. Add HTTP client logic to call OFREP endpoints -4. Handle error cases and response codes according to the specification -5. Register your provider in the [OpenFeature ecosystem](https://github.com/open-feature/openfeature.dev/issues) +2. Implement the provider for your SDK according to the guidelines +3. Register your provider in the [OpenFeature ecosystem](https://github.com/open-feature/openfeature.dev/issues) ### For Flag Management System Developers To make your flag management system OFREP-compliant: 1. Implement the [OFREP OpenAPI specification](./service/openapi.yaml) -2. Expose OFREP endpoints at `/ofrep/v1/evaluate/...` -3. Support both bulk evaluation (for client-side) and single flag evaluation (for server-side) -4. Test your implementation with existing OFREP providers -5. Register your system in the [OpenFeature ecosystem](https://github.com/open-feature/openfeature.dev/issues) +2. Test your implementation with existing OFREP providers +3. Register your system in the [OpenFeature ecosystem](https://github.com/open-feature/openfeature.dev/issues) ## Resources From 2d1be5deb5cf65a7bbe356de37a921ff940b78bc Mon Sep 17 00:00:00 2001 From: Michael Beemer Date: Tue, 28 Oct 2025 17:16:34 -0400 Subject: [PATCH 4/4] Apply suggestion from @gemini-code-assist[bot] Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> Signed-off-by: Michael Beemer --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index dca0106..f3a303e 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ ## What is OFREP? -The **OpenFeature Remote Evaluation Protocol (OFREP)** is an API specification for feature flagging that enables vendor-agnostic communication between applications and flag management systems. It defines a standard API layer between the provider and the flag management system, allowing any OpenSource or commercial system to implement the protocol and be compatible with community-maintained providers. +The **OpenFeature Remote Evaluation Protocol (OFREP)** is an API specification for feature flagging that enables vendor-agnostic communication between applications and flag management systems. It defines a standard API layer between the provider and the flag management system, allowing any open source or commercial system to implement the protocol and be compatible with community-maintained providers. ### Key Benefits