Skip to content

Commit d5bea9f

Browse files
joshua-koehlerKwame Efahtiffanyqi
authored
🚩 Feature flags api spec (#2241)
* API specs for flags endpoints * rdme dryrun fixes * rdme validation fixes * updating secschema * Adding order yamls * updating yamls * fix out suffix in openai config * small fix * link markdown with openapi specs * add jsonLogic rule and deprectate old runtime def * fix errors - categorySlug not a thing * same name * Update links * remove redundant slug * add tags with same names as md files * same tag names everywhere * try and match output with slug * add readme deploy id * rename file * fix reference * consistent name * add rdme cli to npm executables * Add custom_properties to request query params * update server base url * add token param * Change base urls to have api. prefix --------- Co-authored-by: Kwame Efah <[email protected]> Co-authored-by: Tiffany Qi <[email protected]>
1 parent 8bf1d23 commit d5bea9f

File tree

12 files changed

+15763
-7363
lines changed

12 files changed

+15763
-7363
lines changed

‎openapi/openapi.config.yaml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,9 @@ apis:
88
export:
99
root: ./src/export.openapi.yaml
1010
output: ./out/event-export-api.json
11+
featureflags:
12+
root: ./src/feature-flags.openapi.yaml
13+
output: ./out/feature-flags-api.json
1114
gdpr:
1215
root: ./src/gdpr.openapi.yaml
1316
output: ./out/gdpr-api-2.json

‎openapi/src/common/feature-flags-api.yaml‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
server:
2+
url: https://{regionAndDomain}.com
3+
description: Mixpanel's feature flags API server.
4+
variables:
5+
regionAndDomain:
6+
default: 'api.mixpanel'
7+
enum:
8+
- 'api.mixpanel'
9+
- 'api.eu.mixpanel'
10+
- 'api.in.mixpanel'
11+
description: >
12+
The server location to be used:
13+
* `api.mixpanel` - The default (US) servers used for most projects
14+
* `api.eu.mixpanel` - EU servers if you are enrolled in EU Data Residency
15+
* `api.in.mixpanel` - India servers if you are enrolled in India Data Residency

‎openapi/src/feature-flags.openapi.yaml‎

Lines changed: 352 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,352 @@
1+
openapi: 3.0.2
2+
x-readme-deploy-id: feature-flags-api
3+
info:
4+
title: Feature Flags API
5+
description: >-
6+
Use the Feature Flags API to evaluate feature flags for users and retrieve feature flag definitions.
7+
contact:
8+
url: 'https://mixpanel.com/get-support'
9+
license:
10+
name: MIT
11+
url: https://opensource.org/licenses/MIT
12+
version: 1.0.0
13+
servers:
14+
- $ref: ./common/feature-flags-api.yaml#/server
15+
tags:
16+
- name: Get Variant Assignments
17+
description: Evaluate feature flags for a specific user
18+
- name: Get Flag Definitions
19+
description: Retrieve feature flag definitions
20+
paths:
21+
/flags:
22+
get:
23+
operationId: get-variant-assignments
24+
security:
25+
- ProjectSecret: []
26+
parameters:
27+
- $ref: '#/components/parameters/ProjectToken'
28+
- name: context
29+
in: query
30+
description: 'URL-encoded JSON object containing evaluation context with distinct_id (required) and optional device_id and custom_properties object'
31+
required: true
32+
schema:
33+
type: string
34+
example: '%7B++%22distinct_id%22%3A%22user123%22%2C++%22device_id%22%3A%22device456%22%2C++%22custom_properties%22%3A+%7B++++%22some_key%22%3A+%22some_value%22%2C++++%22another_key%22%3A+32++%7D%7D%22'
35+
tags:
36+
- Get Variant Assignments
37+
summary: Evaluate Feature Flags (GET)
38+
description: Evaluate all enabled feature flags for a user with the provided context. Returns selected variants for flags the user is eligible for.
39+
responses:
40+
'200':
41+
description: Success
42+
content:
43+
application/json:
44+
schema:
45+
$ref: '#/components/schemas/EvaluateFlagsResponse'
46+
'400':
47+
$ref: ./common/responses.yaml#/400BadRequest
48+
'401':
49+
$ref: ./common/responses.yaml#/401Unauthorized
50+
'403':
51+
$ref: ./common/responses.yaml#/403Forbidden
52+
/flags/definitions:
53+
get:
54+
operationId: get-flag-definitions
55+
security:
56+
- ProjectSecret: []
57+
parameters:
58+
- $ref: '#/components/parameters/ProjectToken'
59+
tags:
60+
- Get Flag Definitions
61+
summary: Get Feature Flag Definitions
62+
description: Retrieve all enabled feature flag definitions for the authenticated project. Returns complete flag metadata including rulesets, variants, and rollout configurations.
63+
responses:
64+
'200':
65+
description: Success
66+
content:
67+
application/json:
68+
schema:
69+
$ref: '#/components/schemas/FlagDefinitionsResponse'
70+
'401':
71+
$ref: ./common/responses.yaml#/401Unauthorized
72+
'403':
73+
$ref: ./common/responses.yaml#/403Forbidden
74+
components:
75+
securitySchemes:
76+
$ref: ./common/securitySchemes.yaml
77+
parameters:
78+
ProjectToken:
79+
name: token
80+
in: query
81+
schema:
82+
type: string
83+
description: 'Your project token'
84+
required: true
85+
schemas:
86+
EvaluateFlagsRequest:
87+
title: EvaluateFlagsRequest
88+
description: Request body for feature flag evaluation
89+
type: object
90+
required:
91+
- context
92+
properties:
93+
context:
94+
$ref: '#/components/schemas/EvaluationContext'
95+
EvaluationContext:
96+
title: EvaluationContext
97+
description: Context object containing user information and properties for flag evaluation
98+
type: object
99+
required:
100+
- distinct_id
101+
properties:
102+
distinct_id:
103+
type: string
104+
description: The distinct ID of the user to evaluate flags for
105+
example: 'user123'
106+
device_id:
107+
type: string
108+
description: Optional device ID. If not provided, distinct_id will be used
109+
example: 'device456'
110+
custom_properties:
111+
type: object
112+
description: Optional runtime parameters for evaluation by runtime_evaluation_rule in rollout definitions
113+
additionalProperties: true
114+
example:
115+
country: 'US'
116+
platform: 'web'
117+
EvaluateFlagsResponse:
118+
title: EvaluateFlagsResponse
119+
description: Response containing evaluated feature flags for the user
120+
type: object
121+
required:
122+
- flags
123+
properties:
124+
flags:
125+
type: object
126+
additionalProperties:
127+
$ref: '#/components/schemas/SelectedVariant'
128+
description: Map of flag keys to their selected variants
129+
example:
130+
new_checkout_flow:
131+
variant_key: 'treatment'
132+
variant_value: true
133+
experiment_id: 'exp_123'
134+
is_experiment_active: true
135+
SelectedVariant:
136+
title: SelectedVariant
137+
description: The selected variant for a feature flag
138+
type: object
139+
required:
140+
- variant_key
141+
- variant_value
142+
properties:
143+
variant_key:
144+
type: string
145+
description: The key of the selected variant
146+
example: 'treatment'
147+
variant_value:
148+
description: The value of the selected variant (can be any type)
149+
oneOf:
150+
- type: string
151+
- type: number
152+
- type: boolean
153+
- type: object
154+
example: true
155+
experiment_id:
156+
type: string
157+
description: The ID of the associated experiment, if any
158+
example: 'exp_123'
159+
is_experiment_active:
160+
type: boolean
161+
description: Whether the associated experiment is currently active
162+
example: true
163+
is_qa_tester:
164+
type: boolean
165+
description: Whether the user was identified as a QA tester
166+
example: false
167+
FlagDefinitionsResponse:
168+
title: FlagDefinitionsResponse
169+
description: Response containing all enabled feature flag definitions
170+
type: object
171+
required:
172+
- flags
173+
properties:
174+
flags:
175+
type: array
176+
items:
177+
$ref: '#/components/schemas/ExperimentationFlagMetadata'
178+
description: Array of enabled feature flag definitions
179+
ExperimentationFlagMetadata:
180+
title: ExperimentationFlagMetadata
181+
description: Complete metadata for a feature flag
182+
type: object
183+
required:
184+
- id
185+
- name
186+
- key
187+
- status
188+
- project_id
189+
- workspace_id
190+
- ruleset
191+
- context
192+
properties:
193+
id:
194+
type: string
195+
description: Unique identifier for the flag
196+
example: 'flag_abc123'
197+
name:
198+
type: string
199+
description: Human-readable name of the flag
200+
example: 'New Checkout Flow'
201+
key:
202+
type: string
203+
description: Unique key used to reference the flag
204+
example: 'new_checkout_flow'
205+
status:
206+
type: string
207+
enum: ['enabled', 'disabled', 'archived']
208+
description: Current status of the flag
209+
example: 'enabled'
210+
project_id:
211+
type: integer
212+
format: int32
213+
description: ID of the project this flag belongs to
214+
example: 12345
215+
workspace_id:
216+
type: integer
217+
format: int64
218+
description: ID of the workspace (dataview) this flag belongs to
219+
example: 67890
220+
ruleset:
221+
$ref: '#/components/schemas/RuleSet'
222+
context:
223+
type: string
224+
description: The context variable used for flag evaluation (e.g., distinct_id, device_id)
225+
example: 'device_id'
226+
experiment_id:
227+
type: string
228+
description: ID of the associated experiment, if any
229+
example: 'exp_123'
230+
is_experiment_active:
231+
type: boolean
232+
description: Whether the associated experiment is currently active
233+
example: true
234+
RuleSet:
235+
title: RuleSet
236+
description: Complete ruleset for a feature flag including variants and rollout configuration
237+
type: object
238+
required:
239+
- variants
240+
- rollout
241+
properties:
242+
variants:
243+
type: array
244+
items:
245+
$ref: '#/components/schemas/Variant'
246+
description: Array of variant definitions for this flag
247+
rollout:
248+
type: array
249+
items:
250+
$ref: '#/components/schemas/Rollout'
251+
description: Array of rollout rules defining how the flag is distributed
252+
test:
253+
$ref: '#/components/schemas/TestUsers'
254+
Variant:
255+
title: Variant
256+
description: A variant definition for a feature flag
257+
type: object
258+
required:
259+
- key
260+
- value
261+
- is_control
262+
- split
263+
properties:
264+
key:
265+
type: string
266+
description: Unique key for this variant
267+
example: 'treatment'
268+
value:
269+
description: The value for this variant (can be any type)
270+
oneOf:
271+
- type: string
272+
- type: number
273+
- type: boolean
274+
- type: object
275+
example: true
276+
is_control:
277+
type: boolean
278+
description: Whether this is the control variant
279+
example: false
280+
is_sticky:
281+
type: boolean
282+
description: Whether users should stick to this variant once assigned
283+
example: true
284+
split:
285+
type: number
286+
format: double
287+
description: The proportion of users that should receive this variant (0.0 to 1.0)
288+
example: 0.5
289+
Rollout:
290+
title: Rollout
291+
description: A rollout rule defining how a flag is distributed to a cohort
292+
type: object
293+
required:
294+
- rollout_percentage
295+
properties:
296+
rollout_percentage:
297+
type: number
298+
format: double
299+
description: The percentage of the cohort that should receive this flag (0.0 to 1.0)
300+
example: 0.8
301+
cohort_hash:
302+
type: string
303+
description: Hash of the cohort definition for lookup
304+
example: 'cohort_abc123'
305+
runtime_evaluation_rule:
306+
type: object
307+
additionalProperties: true
308+
description: JsonLogic rule that's evaluated at request time based on runtime parameters in the request
309+
example:
310+
platform: 'web'
311+
runtime_evaluation_definition:
312+
deprecated: true
313+
type: object
314+
additionalProperties: true
315+
description: Key-value pairs that are evaluated at request time for cohort matching, replaced by the more powerful runtime_evaluation_rule
316+
example:
317+
platform: 'web'
318+
variant_splits:
319+
type: object
320+
additionalProperties:
321+
type: number
322+
format: double
323+
description: Dictionary mapping variant keys to their allocation splits within this rollout
324+
example:
325+
control: 0.5
326+
treatment: 0.5
327+
variant_override:
328+
deprecated: true
329+
$ref: '#/components/schemas/VariantOverride'
330+
VariantOverride:
331+
deprecated: true
332+
title: VariantOverride
333+
description: Override to force a specific variant for a rollout rule (replaced by variant_splits)
334+
type: object
335+
properties:
336+
key:
337+
type: string
338+
description: The variant key to force
339+
example: 'treatment'
340+
TestUsers:
341+
title: TestUsers
342+
description: Mapping of test users to their assigned variants
343+
type: object
344+
properties:
345+
users:
346+
type: object
347+
additionalProperties:
348+
type: string
349+
description: Map of distinct_id to variant_key for QA testing
350+
example:
351+
qa_user_1: 'treatment'
352+
qa_user_2: 'control'

0 commit comments

Comments
 (0)