feat: OpenAPI proposal for V1 OFREP

.adr-dir

@@ -0,0 +1 @@
+./service/adrs

.gitignore

@@ -1 +1,4 @@
+.DS_Store
+.vscode
 .idea
+.gen

service/adrs/0001-json-over-http-for-the-protocol.md

@@ -0,0 +1,24 @@
+# 1. JSON over HTTP for the protocol
+
+Date: 2024-02-29
+
+## Status
+
+Accepted
+
+## Context
+
+OFREP needs a network protocol and serialization format for the feature flag evaluation information.
+The protocol and serialization format must be supported in web, mobile and server environments.
+
+## Decision
+
+Technology selection was based on the [survey feedback from vendors](https://docs.google.com/forms/d/1NzqKx57XvRK_2lRQOFCRmF5exet6f15-sCjdEy0HCS8#responses).
+The majority of the vendors were using JSON & HTTP in their current implementations.
+Based on this, it was decided to use JSON over HTTP for OFREP.
+
+## Consequences
+
+- Web, mobile and server environments have great support for JSON over HTTP
+- Many developers are familiar with this technology which may reduce the implementation burden
+- Most vendors are already using this technology, hence it will be easier for them to adopt OFREP

service/adrs/0002-two-evaluation-endpoints.md

@@ -0,0 +1,28 @@
+# 2. Two evaluation endpoints
+
+Date: 2024-03-01
+
+## Status
+
+Accepted
+
+## Context
+
+Evaluating flags in the static context paradigm, is often done by bulk evaluating flags and updating them if needed.
+For example, [frontend would most times load all flags](https://openfeature.dev/blog/catering-to-the-client-side). 
+And the payload is cached to prevent loading times and to avoid overloading the feature flagging service.
+
+In the dynamic context paradigm, flags are usually evaluated on demand.
+For example, backend service often evaluates flags based on the information present in the specific request.
+This makes bulk evaluation less favourable for dynamic context paradigm. 
+
+## Decision
+
+OFREP contains two endpoints, one for individual flag evaluations and the other for bulk evaluations.
+Individual flag evaluation is preferred for the dynamic context paradigm whereas the bulk evaluation is preferred for static context paradigm.
+
+## Consequences
+
+- OFREP supports single and bulk evaluations
+- Each endpoint might evolve to better serve the specific OpenFeature paradigm
+- It might become challenging to prevent the endpoints from diverging

service/adrs/0003-no-flag-type-in-request-or-response.md

@@ -0,0 +1,33 @@
+# 3. No flag type in request or response
+
+Date: 2024-03-01
+
+## Status
+
+Accepted
+
+## Context
+
+Feature flags in OpenFeature can have several different types.
+Often you see `boolean | number | string | structure` and often specific number types like `integer | float`.
+Details can be seen in the [OF specification](https://openfeature.dev/specification/types).
+
+When evaluating a flag via OFREP, the provider implementation will have to parse the flag value from the JSON response.
+There are different approaches to this. Some feature flagging services define an expected flag type in the request.
+Some include the flag type or even a schema in the response and some do not specify any type either in request or response.
+
+## Decision
+
+In the community meeting on 2024-02-29, it was concluded **not** to include type details in any payload.
+The reason for this is to keep the API simple until there is a need for improvements.
+
+Provider implementations are expected to infer the types from the JSON response.
+Given that OpenFeature evaluation supports primitive types, value conversions may focus on evaluation type and deserialized JSON value type.
+To differentiate integers and floats, the provider implementations will need to enforce JSON number parsing rules in the respective language.
+
+## Consequences
+
+- OFREP stays simple
+- Parsing flag types can be done by using the JSON value type
+- Parsing language specific types like floats will be up to the provider implementations
+- Not having the request type in the request results in the feature flagging service, not knowing when there is a flag type mismatch

service/adrs/0004-no-flag-filter-in-bulk-evaluation-request.md

@@ -0,0 +1,23 @@
+# 4. No flag filter in bulk evaluation request
+
+Date: 2024-03-01
+
+## Status
+
+Accepted
+
+## Context
+
+There can be cases where bulk evaluation evaluates and returns hundreds or thousands of flags.
+Some feature flagging systems define filters that specify which flags should be bulk evaluated.
+
+## Decision
+
+OFREP does not specify a `flags` property that specifies the flags to be bulk evaluated.
+For systems that rely on a list of flags, there is an alternative to include them through the `context` object.
+
+## Consequences
+
+- There is no standardized way of filtering flags
+    - Flags can still be filtered via the evaluation context
+- OFREP stays simple and the evaluation only depends on context and authorization 

service/adrs/0005-polling-for-bulk-evaluation-changes.md

@@ -0,0 +1,38 @@
+# 5. Polling for bulk evaluation changes
+
+Date: 2024-03-01
+
+## Status
+
+Accepted
+
+## Context
+
+In most systems, feature flags can be changed at any time.
+This is a challenge for bulk evaluation where the typical use case is caching the evaluated flags and evaluating from the cache.
+
+Many feature flagging systems provide ways to inform clients about changes in feature flag values.
+This can reach from polling clients over to server-sent events and websockets.
+
+Some providers also define polling endpoints that list changed feature flags instead of polling the evaluation endpoint.
+
+The [vendor survey](https://docs.google.com/forms/d/1NzqKx57XvRK_2lRQOFCRmF5exet6f15-sCjdEy0HCS8#responses) showed that many vendors do simple polling from clients or SSE.
+
+## Decision
+
+OFREP intends provider implementations to do polling. For now no streaming like SSEs or websockets is specified.
+The reason is simplicity and openness to define additional mechanisms later.
+
+Optional [ETag](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag) can be used with the bulk evaluation endpoint.
+The motivation here is to save wire bandwidth and evaluation burden on the flag management system.
+If present in response, the implementation will attach ETag when polling and respect 304 responses from the flag management system.
+
+Individual flag evaluations may be cached to increase performance.
+But this is out of the scope of the OpenAPI specification and is an implementation detail of the provider.
+
+## Consequences
+
+- OFREP stays simple
+- There is no way of implementing real-time flag updates for now
+  - Frequent evaluations from polling clients may introduce additional processing for feature flagging services
+- Additional change detection mechanisms will need to be added later