Skip to content

Commit 5da059b

Browse files
authored
feat(specs): add A/B test settings endpoints to abtesting-v3 (#6786)
1 parent 0fff57e commit 5da059b

12 files changed

Lines changed: 294 additions & 28 deletions

File tree

โ€Žgenerators/src/main/java/com/algolia/codegen/cts/tests/Snippet.javaโ€Ž

Lines changed: 3 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,6 @@
77
import com.fasterxml.jackson.core.JsonProcessingException;
88
import java.util.*;
99
import org.openapitools.codegen.CodegenOperation;
10-
import org.openapitools.codegen.CodegenResponse;
1110

1211
public class Snippet {
1312

@@ -97,14 +96,9 @@ public void addMethodCall(Map<String, Object> context, ParametersWithDataType pa
9796
context.put("requestOptions", requestOptionsContext);
9897
}
9998

100-
// Determines whether the endpoint is expected to return a response payload deserialized
101-
// and therefore a variable to store it into.
102-
context.put("hasResponse", true);
103-
for (CodegenResponse response : ope.responses) {
104-
if (response.code.equals("204")) {
105-
context.put("hasResponse", false);
106-
}
107-
}
99+
// Only render a response variable when the operation returns a payload: a 204, or a 200
100+
// without a body, both have no return type.
101+
context.put("hasResponse", ope.returnType != null && !ope.returnType.isEmpty());
108102

109103
paramsType.enhanceParameters(parameters, context, ope);
110104
} catch (CTSException e) {

โ€Žgenerators/src/main/java/com/algolia/codegen/cts/tests/TestsClient.javaโ€Ž

Lines changed: 3 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,6 @@
1010
import java.util.Map;
1111
import org.openapitools.codegen.CodegenModel;
1212
import org.openapitools.codegen.CodegenOperation;
13-
import org.openapitools.codegen.CodegenResponse;
1413
import org.openapitools.codegen.SupportingFile;
1514

1615
public class TestsClient extends TestsGenerator {
@@ -168,14 +167,9 @@ public void run(Map<String, CodegenModel> models, Map<String, CodegenOperation>
168167
// default to true because most api calls are asynchronous
169168
stepOut.put("isAsyncMethod", (boolean) ope.vendorExtensions.getOrDefault("x-asynchronous-helper", true));
170169

171-
// Determines whether the endpoint is expected to return a response payload
172-
// deserialized and therefore a variable to store it into.
173-
stepOut.put("hasResponse", true);
174-
for (CodegenResponse response : ope.responses) {
175-
if (response.code.equals("204")) {
176-
stepOut.put("hasResponse", false);
177-
}
178-
}
170+
// Only render a response variable when the operation returns a payload: a 204, or a
171+
// 200 without a body, both have no return type.
172+
stepOut.put("hasResponse", ope.returnType != null && !ope.returnType.isEmpty());
179173

180174
// set on testOut because we need to wrap everything for java.
181175
testOut.put("isHelper", isHelper);

โ€Žgenerators/src/main/java/com/algolia/codegen/cts/tests/TestsRequest.javaโ€Ž

Lines changed: 3 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,6 @@
1313
import java.util.*;
1414
import org.openapitools.codegen.CodegenModel;
1515
import org.openapitools.codegen.CodegenOperation;
16-
import org.openapitools.codegen.CodegenResponse;
1716
import org.openapitools.codegen.SupportingFile;
1817

1918
public class TestsRequest extends TestsGenerator {
@@ -257,15 +256,9 @@ public void run(Map<String, CodegenModel> models, Map<String, CodegenOperation>
257256

258257
addRequestOptions(paramsType, req.requestOptions, test);
259258

260-
// Determines whether the endpoint is expected to return a response payload deserialized
261-
// and therefore a variable to store it into.
262-
test.put("hasResponse", true);
263-
264-
for (CodegenResponse response : ope.responses) {
265-
if (response.code.equals("204")) {
266-
test.put("hasResponse", false);
267-
}
268-
}
259+
// Only render a response variable when the operation returns a payload: a 204, or a 200
260+
// without a body, both have no return type.
261+
test.put("hasResponse", ope.returnType != null && !ope.returnType.isEmpty());
269262

270263
paramsType.enhanceParameters(req.parameters, test, ope);
271264
tests.add(test);

โ€Žspecs/abtesting-v3/common/parameters.ymlโ€Ž

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -163,3 +163,13 @@ direction:
163163
- asc
164164
- desc
165165
example: desc
166+
167+
VariantID:
168+
in: path
169+
name: variantId
170+
description: One-based index of the A/B test variant. The control is variant 1.
171+
required: true
172+
schema:
173+
type: integer
174+
minimum: 1
175+
example: 2
Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
FeatureSettings:
2+
type: object
3+
description: Feature-specific settings captured for a variant.
4+
additionalProperties: false
5+
properties:
6+
name:
7+
type: string
8+
description: Name of the feature the settings belong to.
9+
example: 'reranking'
10+
settings:
11+
description: Feature settings payload. The shape depends on the feature.
12+
required:
13+
- name
14+
- settings
15+
16+
VariantSettings:
17+
type: object
18+
description: Settings captured for one A/B test variant.
19+
additionalProperties: false
20+
properties:
21+
variantId:
22+
type: integer
23+
description: One-based index of the variant within the A/B test. The control is variant 1.
24+
example: 2
25+
applied:
26+
type: boolean
27+
description: Whether the variant's settings have been applied to the control index.
28+
featuresSettings:
29+
type: array
30+
description: Feature-specific settings captured for the variant.
31+
items:
32+
$ref: '#/FeatureSettings'
33+
indexSettings:
34+
type: object
35+
description: Index settings captured for the variant.
36+
applyTimestamp:
37+
type: string
38+
description: Date and time when the variant's settings were applied to the control index, in RFC 3339 format.
39+
example: 2023-06-17T00:00:00Z
40+
revertTimestamp:
41+
type: string
42+
description: Date and time when the applied settings were reverted on the control index, in RFC 3339 format.
43+
example: 2023-06-18T00:00:00Z
44+
declaredTimestamp:
45+
type: string
46+
description: Date and time when the variant's settings were captured, in RFC 3339 format.
47+
example: 2023-06-16T00:00:00Z
48+
expiredTimestamp:
49+
type: string
50+
description: Date and time when the captured settings expired, in RFC 3339 format.
51+
example: 2023-07-16T00:00:00Z
52+
required:
53+
- variantId
54+
- applied
55+
56+
ABTestSettingsResponse:
57+
type: object
58+
description: Captured settings of an A/B test.
59+
additionalProperties: false
60+
properties:
61+
abtestSettings:
62+
type: array
63+
description: Captured settings for each variant of the A/B test.
64+
items:
65+
$ref: '#/VariantSettings'
66+
controlIndexInUse:
67+
type: boolean
68+
description: Whether another active A/B test is using the control index.
69+
required:
70+
- abtestSettings
71+
- controlIndexInUse
72+
73+
SaveSettingsRequest:
74+
type: object
75+
description: Options for capturing a variant's settings.
76+
additionalProperties: false
77+
properties:
78+
saveFeaturesSettings:
79+
type: boolean
80+
description: Whether to also capture the variant's index settings and feature-specific settings. This must be true for A/B tests whose variants use different indices so that the captured variant settings can later be applied.
81+
default: false
Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
post:
2+
tags:
3+
- abtest
4+
operationId: applyVariantSettings
5+
x-acl:
6+
- analytics
7+
- editSettings
8+
summary: Apply a variant's captured settings to the control index
9+
description: |
10+
Applies the captured settings of the given variant to the control index.
11+
12+
The settings must first be captured with the `saveVariantSettings` operation. To revert previously applied settings on the control index, use this operation with the control variant (variant 1).
13+
14+
Settings can be applied up to 14 days after the A/B test ends, and reverted up to 15 days after. Later requests return `400`.
15+
16+
Each set of captured settings can only be applied once, and settings that were reverted can't be applied again. Both cases return `400`.
17+
18+
The control index must not be in use by an active A/B test. Otherwise, the request returns `422`.
19+
parameters:
20+
- $ref: '../common/parameters.yml#/ID'
21+
- $ref: '../common/parameters.yml#/VariantID'
22+
responses:
23+
'200':
24+
description: OK
25+
headers:
26+
x-ratelimit-limit:
27+
$ref: '../../common/responses/rateLimit.yml#/x-ratelimit-limit'
28+
x-ratelimit-remaining:
29+
$ref: '../../common/responses/rateLimit.yml#/x-ratelimit-remaining'
30+
x-ratelimit-reset:
31+
$ref: '../../common/responses/rateLimit.yml#/x-ratelimit-reset'
32+
'400':
33+
$ref: '../../common/responses/BadRequest.yml'
34+
'402':
35+
$ref: '../../common/responses/FeatureNotEnabled.yml'
36+
'403':
37+
$ref: '../../common/responses/MethodNotAllowed.yml'
38+
'404':
39+
$ref: '../../common/responses/IndexNotFound.yml'
40+
'422':
41+
$ref: '../../common/responses/UnprocessableEntity.yml'
Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
get:
2+
tags:
3+
- abtest
4+
operationId: getABTestSettings
5+
x-acl:
6+
- analytics
7+
summary: Retrieve captured A/B test settings
8+
description: |
9+
Retrieves the settings captured for each variant of an A/B test, and whether another active A/B test is using the control index.
10+
11+
Settings are captured by the `saveVariantSettings` operation. The response includes an entry for the control (variant 1) alongside the captured variant, so the control's original configuration can be restored later.
12+
13+
Returns `404` if the A/B test doesn't exist or no settings have been captured for it.
14+
parameters:
15+
- $ref: '../common/parameters.yml#/ID'
16+
responses:
17+
'200':
18+
description: OK
19+
headers:
20+
x-ratelimit-limit:
21+
$ref: '../../common/responses/rateLimit.yml#/x-ratelimit-limit'
22+
x-ratelimit-remaining:
23+
$ref: '../../common/responses/rateLimit.yml#/x-ratelimit-remaining'
24+
x-ratelimit-reset:
25+
$ref: '../../common/responses/rateLimit.yml#/x-ratelimit-reset'
26+
content:
27+
application/json:
28+
schema:
29+
$ref: '../common/schemas/ABTestSettings.yml#/ABTestSettingsResponse'
30+
'400':
31+
$ref: '../../common/responses/BadRequest.yml'
32+
'402':
33+
$ref: '../../common/responses/FeatureNotEnabled.yml'
34+
'403':
35+
$ref: '../../common/responses/MethodNotAllowed.yml'
36+
'404':
37+
description: A/B test or captured settings not found.
38+
content:
39+
application/json:
40+
schema:
41+
$ref: '../../common/schemas/ErrorBase.yml'
42+
'422':
43+
$ref: '../../common/responses/UnprocessableEntity.yml'
Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
post:
2+
tags:
3+
- abtest
4+
operationId: saveVariantSettings
5+
x-acl:
6+
- analytics
7+
- editSettings
8+
summary: Capture a variant's settings and stop the A/B test
9+
description: |
10+
Captures the settings of the given variant and of the control, then stops the A/B test.
11+
12+
The captured settings can later be applied to the control index with the `applyVariantSettings` operation, and read back with the `getABTestSettings` operation.
13+
14+
The A/B test must have reached 80% of its planned duration. Earlier requests return `400`.
15+
16+
Settings can only be captured once per A/B test. A second request returns `409`.
17+
18+
`synonyms` and `enableRules` are not captured, so applying the captured settings never changes them on the control index.
19+
parameters:
20+
- $ref: '../common/parameters.yml#/ID'
21+
- $ref: '../common/parameters.yml#/VariantID'
22+
requestBody:
23+
required: true
24+
content:
25+
application/json:
26+
schema:
27+
$ref: '../common/schemas/ABTestSettings.yml#/SaveSettingsRequest'
28+
responses:
29+
'200':
30+
description: OK
31+
headers:
32+
x-ratelimit-limit:
33+
$ref: '../../common/responses/rateLimit.yml#/x-ratelimit-limit'
34+
x-ratelimit-remaining:
35+
$ref: '../../common/responses/rateLimit.yml#/x-ratelimit-remaining'
36+
x-ratelimit-reset:
37+
$ref: '../../common/responses/rateLimit.yml#/x-ratelimit-reset'
38+
'400':
39+
$ref: '../../common/responses/BadRequest.yml'
40+
'402':
41+
$ref: '../../common/responses/FeatureNotEnabled.yml'
42+
'403':
43+
$ref: '../../common/responses/MethodNotAllowed.yml'
44+
'404':
45+
$ref: '../../common/responses/IndexNotFound.yml'
46+
'409':
47+
$ref: '../../common/responses/Conflict.yml'
48+
'422':
49+
$ref: '../../common/responses/UnprocessableEntity.yml'

โ€Žspecs/abtesting-v3/spec.ymlโ€Ž

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -99,6 +99,12 @@ paths:
9999
$ref: 'paths/estimate.yml'
100100
/3/abtests/{id}/timeseries:
101101
$ref: 'paths/timeseries.yml'
102+
/3/abtests/{id}/settings:
103+
$ref: 'paths/settings.yml'
104+
/3/abtests/{id}/settings/{variantId}:
105+
$ref: 'paths/variantSettings.yml'
106+
/3/abtests/{id}/settings/{variantId}/apply:
107+
$ref: 'paths/applyVariantSettings.yml'
102108

103109
# ###############
104110
# ### Helpers ###
Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
[
2+
{
3+
"testName": "applyVariantSettings",
4+
"parameters": {
5+
"id": 42,
6+
"variantId": 2
7+
},
8+
"request": {
9+
"path": "/3/abtests/42/settings/2/apply",
10+
"method": "POST"
11+
}
12+
}
13+
]

0 commit comments

Comments
ย (0)