Skip to content

Commit 4cab83c

Browse files
authored
feat(specs): add externalProvider source for CompAPI client (#7073)
## ๐Ÿงญ What and Why ๐ŸŽŸ JIRA Ticket: https://algolia.atlassian.net/browse/CMP-897 Adds public API support for referencing external provider (e.g. Retail Media Network) configurations from Composition API sources, per the RFC [External Provider Sources in Composition API](https://algolia.atlassian.net/wiki/spaces/CMP/pages/7358120173/RFC+-+External+Provider+Sources+in+Composition+API). Previously, compositions could only retrieve results via Algolia `search` & `recommend`. This lets customers delegate result retrieval to a configured external provider instead. ### Changes included: - Add a new `externalProvider` source type, usable as both the main source and an injected-item source (`index`, `configurationID`, `configurationParams`, `params`, `ordering`) - Add `externalProvider.configurationParams` to the Run request body, to override provider parameters at query time - Add an `errors` field to the Run response, to surface non-critical processing errors (e.g. a provider failure that fell back to another result set) ## ๐Ÿงช Test - `yarn cli build specs composition` bundles and lints cleanly with the new schemas - Added CTS fixtures in `tests/CTS/requests/composition/{putComposition,putCompositionRule,search}.json`.
1 parent 8f93fe4 commit 4cab83c

11 files changed

Lines changed: 313 additions & 1 deletion

File tree

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
externalProviderOrdering:
2+
type: string
3+
description: |
4+
Ordering to apply on the items retrieved from the external provider. 'default' uses the relevance ranking from the Algolia retrieval step. 'providerDefined' uses the ordering returned by the external provider.
5+
enum: ['default', 'providerDefined']
6+
default: 'providerDefined'

โ€Žspecs/composition/common/schemas/components/injection/InjectedItem.ymlโ€Ž

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,7 @@ injectedItemSource:
4444
- $ref: './InjectedItemSource.yml#/injectedItemSearchSource'
4545
- $ref: './InjectedItemSource.yml#/injectedItemExternalSource'
4646
- $ref: './InjectedItemSource.yml#/injectedItemRecommendSource'
47+
- $ref: './InjectedItemSource.yml#/injectedItemExternalProviderSource'
4748

4849
dedupPositioning:
4950
type: string

โ€Žspecs/composition/common/schemas/components/injection/InjectedItemSource.ymlโ€Ž

Lines changed: 36 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -83,4 +83,39 @@ injectedItemRecommendSource:
8383
- model
8484
- threshold
8585
required:
86-
- recommend
86+
- recommend
87+
88+
injectedItemExternalProviderSource:
89+
description: Injected items will originate from a request to an external provider configuration.
90+
x-discriminator-fields:
91+
- externalProvider
92+
type: object
93+
additionalProperties: false
94+
properties:
95+
externalProvider:
96+
title: injectedItemExternalProvider
97+
type: object
98+
additionalProperties: false
99+
properties:
100+
index:
101+
type: string
102+
description: Algolia index used to fetch the records.
103+
example: Products
104+
configurationID:
105+
type: string
106+
description: Identifier of the external provider configuration.
107+
example: 'my-rmn-connection'
108+
configurationParams:
109+
type: object
110+
additionalProperties: true
111+
description: Default values for the configuration placeholders that are not reserved Composition placeholders.
112+
example: {campaign_id: 'winter-sale', customer_id: 'user123'}
113+
params:
114+
$ref: './SearchQueryParams.yml#/injectedItemsQueryParameters'
115+
ordering:
116+
$ref: './ExternalProviderSource.yml#/externalProviderOrdering'
117+
required:
118+
- index
119+
- configurationID
120+
required:
121+
- externalProvider

โ€Žspecs/composition/common/schemas/components/injection/Main.ymlโ€Ž

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,3 +11,4 @@ injectionMainSource:
1111
oneOf:
1212
- $ref: './MainSource.yml#/injectionMainSearchSource'
1313
- $ref: './MainSource.yml#/injectionMainRecommendSource'
14+
- $ref: './MainSource.yml#/injectionMainExternalProviderSource'

โ€Žspecs/composition/common/schemas/components/injection/MainSource.ymlโ€Ž

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -54,3 +54,38 @@ injectionMainRecommendSource:
5454
- threshold
5555
required:
5656
- recommend
57+
58+
injectionMainExternalProviderSource:
59+
description: Organic result set will originate from a request to an external provider configuration.
60+
x-discriminator-fields:
61+
- externalProvider
62+
type: object
63+
additionalProperties: false
64+
properties:
65+
externalProvider:
66+
title: mainExternalProvider
67+
type: object
68+
additionalProperties: false
69+
properties:
70+
index:
71+
type: string
72+
description: Algolia index used to fetch the records.
73+
example: Products
74+
configurationID:
75+
type: string
76+
description: Identifier of the external provider configuration.
77+
example: 'my-rmn-connection'
78+
configurationParams:
79+
type: object
80+
additionalProperties: true
81+
description: Default values for the configuration placeholders that are not reserved Composition placeholders.
82+
example: {campaign_id: 'winter-sale', customer_id: 'user123'}
83+
params:
84+
$ref: './SearchQueryParams.yml#/mainInjectionQueryParameters'
85+
ordering:
86+
$ref: './ExternalProviderSource.yml#/externalProviderOrdering'
87+
required:
88+
- index
89+
- configurationID
90+
required:
91+
- externalProvider

โ€Žspecs/composition/common/schemas/requestBodies/RunParams.ymlโ€Ž

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -64,6 +64,17 @@ params:
6464
userToken:
6565
$ref: '../../params/Search.yml#/userToken'
6666

67+
externalProvider:
68+
title: Run composition external provider parameters as object
69+
type: object
70+
additionalProperties: false
71+
properties:
72+
configurationParams:
73+
type: object
74+
additionalProperties: true
75+
description: Values for non-prefixed configuration placeholders, overriding the composition source's `configurationParams` and the configuration's `defaults`.
76+
example: {customer_id: 'customer123'}
77+
6778
feedsOrder:
6879
type: array
6980
description: |

โ€Žspecs/composition/common/schemas/responses/SearchResponse.ymlโ€Ž

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,5 +13,20 @@ searchResults:
1313
description: Search results.
1414
items:
1515
$ref: './runResponseComponents/SingleResultSet.yml#/searchResultsItem'
16+
errors:
17+
type: array
18+
description: Non-critical errors encountered while processing the request that may have affected the returned results (for example, an external provider failure that fell back to another result set).
19+
items:
20+
$ref: '#/processingError'
1621
required:
1722
- results
23+
24+
processingError:
25+
type: object
26+
additionalProperties: false
27+
properties:
28+
message:
29+
type: string
30+
description: Description of the non-critical error.
31+
required:
32+
- message

โ€Žspecs/composition/paths/search/search.ymlโ€Ž

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,8 @@ post:
2323
$ref: '../../common/schemas/requestBodies/RunParams.yml#/params'
2424
feedsOrder:
2525
$ref: '../../common/schemas/requestBodies/RunParams.yml#/feedsOrder'
26+
externalProvider:
27+
$ref: '../../common/schemas/requestBodies/RunParams.yml#/externalProvider'
2628
responses:
2729
'200':
2830
description: OK

โ€Žtests/CTS/requests/composition/putComposition.jsonโ€Ž

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -824,5 +824,94 @@
824824
}
825825
}
826826
}
827+
},
828+
{
829+
"parameters": {
830+
"compositionID": "my-external-provider-compo",
831+
"composition": {
832+
"objectID": "my-external-provider-compo",
833+
"name": "my external provider composition",
834+
"behavior": {
835+
"injection": {
836+
"main": {
837+
"source": {
838+
"externalProvider": {
839+
"index": "products",
840+
"configurationID": "my-rmn-connection",
841+
"configurationParams": {
842+
"campaign_id": "summer-sale",
843+
"customer_id": "customer-default"
844+
},
845+
"params": {
846+
"filters": "instock:true"
847+
},
848+
"ordering": "providerDefined"
849+
}
850+
}
851+
},
852+
"injectedItems": [
853+
{
854+
"key": "sponsored",
855+
"source": {
856+
"externalProvider": {
857+
"index": "products",
858+
"configurationID": "my-rmn-connection",
859+
"configurationParams": {
860+
"campaign_id": "summer-sale"
861+
}
862+
}
863+
},
864+
"position": 0,
865+
"length": 2
866+
}
867+
]
868+
}
869+
}
870+
}
871+
},
872+
"request": {
873+
"path": "/1/compositions/my-external-provider-compo",
874+
"method": "PUT",
875+
"body": {
876+
"objectID": "my-external-provider-compo",
877+
"name": "my external provider composition",
878+
"behavior": {
879+
"injection": {
880+
"main": {
881+
"source": {
882+
"externalProvider": {
883+
"index": "products",
884+
"configurationID": "my-rmn-connection",
885+
"configurationParams": {
886+
"campaign_id": "summer-sale",
887+
"customer_id": "customer-default"
888+
},
889+
"params": {
890+
"filters": "instock:true"
891+
},
892+
"ordering": "providerDefined"
893+
}
894+
}
895+
},
896+
"injectedItems": [
897+
{
898+
"key": "sponsored",
899+
"source": {
900+
"externalProvider": {
901+
"index": "products",
902+
"configurationID": "my-rmn-connection",
903+
"configurationParams": {
904+
"campaign_id": "summer-sale"
905+
}
906+
}
907+
},
908+
"position": 0,
909+
"length": 2
910+
}
911+
]
912+
}
913+
}
914+
}
915+
}
827916
}
828917
]

โ€Žtests/CTS/requests/composition/putCompositionRule.jsonโ€Ž

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -393,5 +393,93 @@
393393
}
394394
}
395395
}
396+
},
397+
{
398+
"parameters": {
399+
"compositionID": "compositionID",
400+
"objectID": "rule-with-external-provider-source",
401+
"compositionRule": {
402+
"objectID": "rule-with-external-provider-source",
403+
"conditions": [
404+
{
405+
"anchoring": "contains",
406+
"pattern": "harry"
407+
}
408+
],
409+
"consequence": {
410+
"behavior": {
411+
"injection": {
412+
"main": {
413+
"source": {
414+
"search": {
415+
"index": "my-index"
416+
}
417+
}
418+
},
419+
"injectedItems": [
420+
{
421+
"key": "my-unique-external-provider-group-from-rule-key",
422+
"source": {
423+
"externalProvider": {
424+
"index": "my-index",
425+
"configurationID": "my-rmn-connection",
426+
"configurationParams": {
427+
"campaign_id": "summer-sale"
428+
},
429+
"ordering": "providerDefined"
430+
}
431+
},
432+
"position": 0,
433+
"length": 3
434+
}
435+
]
436+
}
437+
}
438+
}
439+
}
440+
},
441+
"request": {
442+
"path": "/1/compositions/compositionID/rules/rule-with-external-provider-source",
443+
"method": "PUT",
444+
"body": {
445+
"objectID": "rule-with-external-provider-source",
446+
"conditions": [
447+
{
448+
"anchoring": "contains",
449+
"pattern": "harry"
450+
}
451+
],
452+
"consequence": {
453+
"behavior": {
454+
"injection": {
455+
"main": {
456+
"source": {
457+
"search": {
458+
"index": "my-index"
459+
}
460+
}
461+
},
462+
"injectedItems": [
463+
{
464+
"key": "my-unique-external-provider-group-from-rule-key",
465+
"source": {
466+
"externalProvider": {
467+
"index": "my-index",
468+
"configurationID": "my-rmn-connection",
469+
"configurationParams": {
470+
"campaign_id": "summer-sale"
471+
},
472+
"ordering": "providerDefined"
473+
}
474+
},
475+
"position": 0,
476+
"length": 3
477+
}
478+
]
479+
}
480+
}
481+
}
482+
}
483+
}
396484
}
397485
]

0 commit comments

Comments
ย (0)