From 50f3dea0ba5822d23376cc8ecbe8f347572637dd Mon Sep 17 00:00:00 2001 From: Alexey Stysin Date: Fri, 10 Nov 2023 20:26:10 +0200 Subject: [PATCH 1/4] autobidding endpoint documentation --- topsort-api-v2.yml | 194 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 194 insertions(+) diff --git a/topsort-api-v2.yml b/topsort-api-v2.yml index 20f6bf8..3d8071e 100644 --- a/topsort-api-v2.yml +++ b/topsort-api-v2.yml @@ -82,6 +82,15 @@ tags: ## Winner (Sponsored Listings) + + ## Autobidding Result + + + ## Autobidding Bid + + + ## Autobidding Bid Info + security: - BearerAuth: [] @@ -228,6 +237,113 @@ paths: $ref: '#/components/responses/UnauthorizedError' 400: $ref: '#/components/responses/BadRequest' + /bids: + post: + tags: + - Auctions + summary: Create new autobidding requests + operationId: createAutobiddingRequest + requestBody: + description: | + The information describing the contents of the autobidding call. + Topsort will run compute the autobidding bids for each batched autobidding request. + The format of the autobidding request is identical to the auction request. + content: + application/json: + schema: + type: object + properties: + auctions: + type: array + items: + $ref: '#/components/schemas/AuctionRequest' + minItems: 1 + maxItems: 5 + required: + - auctions + example: + auctions: + - type: listings + slots: 1 + category: + disjunctions: + - - c_large + - c_medium + - - c_red + - c_blue + - type: listings + slots: 2 + products: + ids: + - p_PJbnN + - p_ojng4 + - p_8VKDt + - p_Mfk15 + geoTargeting: + location: New York + - type: banners + slots: 1 + slotId: categories-ribbon-banner + category: + id: c_yogurt + - type: banners + slots: 1 + slotId: homepage-banner + required: true + responses: + 201: + description: > + The results of autobidding requests. + The list of bids will contain at most `slots` entries per autobidding request. + It may contain fewer or no entries at all if there aren't enough products with usable bids, + belonging to a campaign with enough remaining budget and not excluded by pacing mechanism. + Bids become unusable if campaign budget is exhausted, the bid is disqualified to preserve spend pacing, etc. + content: + application/json: + schema: + type: object + properties: + results: + type: array + items: + $ref: '#/components/schemas/AutobiddingResult' + minItems: 1 + maxItems: 5 + required: + - results + example: + results: + - winners: + - rank: 1 + type: product + id: p_Mfk11 + resolvedBidId: WyJiX01mazExIiwiMTJhNTU4MjgtOGVhZC00Mjk5LTMyNjYtY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0== + bidInfo: + amount: 42 + error: false + - winners: + - rank: 1 + type: product + id: p_Mfk15 + resolvedBidId: WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0= + bidInfo: + amount: 42 + - rank: 2 + type: product + id: p_PJbnN + resolvedBidId: WyJlX1BKYm5OIiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0= + bidInfo: + amount: 24 + qualityScore: 0.1 + error: false + - winners: [ ] + error: false + 401: + $ref: '#/components/responses/UnauthorizedError' + 400: + $ref: '#/components/responses/BadRequest' + 402: + $ref: '#/components/responses/PaymentRequired' components: responses: @@ -991,6 +1107,84 @@ components: description: The price of a single item in the marketplace currency. example: 12.95 + AutobiddingResult: + type: object + properties: + resultType: + type: string + winners: + type: array + items: + $ref: '#/components/schemas/AutobiddingBid' + description: > + Array of autobidding bid objects in order from highest to lowest according to internal ranking score. + It will be empty if there were no qualifying bids or if there was an error. + error: + type: boolean + description: A boolean indicating whether this auction was resolved successfully. + example: false + required: + - winners + - error + - resultType + + + AutobiddingBid: + description: > + Container for the autobidding bid result, similar to auction winner + type: object + required: + - type + - id + - resolvedBidId + - bidInfo + properties: + rank: + type: integer + format: int32 + description: > + Where the product's bid ranked by the internal ranking score. + In an autobidding response, the bids array is sorted so rank will match the entry's index. + minimum: 1 + type: + type: string + description: The target type of the bid. + enum: + - product + - vendor + - brand + - url + id: + type: string + description: |- + The marketplace's ID of the bid entity, depending on the target of the campaign. + example: p_Mfk15 + resolvedBidId: + type: string + description: An opaque Topsort ID to be used when this item is interacted with. + example: WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0= + bidInfo: + $ref: '#/components/schemas/AutobiddingBidInfo' + + AutobiddingBidInfo: + description: > + Bidding values, including bid amount and optional quality score + type: object + required: + - amount + properties: + amount: + type: integer + format: int64 + description: Bid amount in minimum currency units. + minimum: 1 + qualityScore: + type: number + format: double + description: Optional quality score value + minimum: 0.0 + maximum: 1.0 + securitySchemes: BearerAuth: type: http From 50c11ffc1a22678cfedbb41f83b3a6e933df93e3 Mon Sep 17 00:00:00 2001 From: Alexey Stysin Date: Fri, 10 Nov 2023 20:38:39 +0200 Subject: [PATCH 2/4] prettier --- .idea/inspectionProfiles/Project_Default.xml | 138 ++++++++++++++++++ .../inspectionProfiles/profiles_settings.xml | 6 + .idea/modules.xml | 8 + .idea/openapi.iml | 8 + topsort-api-v2.yml | 9 +- 5 files changed, 164 insertions(+), 5 deletions(-) create mode 100644 .idea/inspectionProfiles/Project_Default.xml create mode 100644 .idea/inspectionProfiles/profiles_settings.xml create mode 100644 .idea/modules.xml create mode 100644 .idea/openapi.iml diff --git a/.idea/inspectionProfiles/Project_Default.xml b/.idea/inspectionProfiles/Project_Default.xml new file mode 100644 index 0000000..cbe3bff --- /dev/null +++ b/.idea/inspectionProfiles/Project_Default.xml @@ -0,0 +1,138 @@ + + + + \ No newline at end of file diff --git a/.idea/inspectionProfiles/profiles_settings.xml b/.idea/inspectionProfiles/profiles_settings.xml new file mode 100644 index 0000000..105ce2d --- /dev/null +++ b/.idea/inspectionProfiles/profiles_settings.xml @@ -0,0 +1,6 @@ + + + + \ No newline at end of file diff --git a/.idea/modules.xml b/.idea/modules.xml new file mode 100644 index 0000000..3b4c6f6 --- /dev/null +++ b/.idea/modules.xml @@ -0,0 +1,8 @@ + + + + + + + + \ No newline at end of file diff --git a/.idea/openapi.iml b/.idea/openapi.iml new file mode 100644 index 0000000..d0876a7 --- /dev/null +++ b/.idea/openapi.iml @@ -0,0 +1,8 @@ + + + + + + + + \ No newline at end of file diff --git a/topsort-api-v2.yml b/topsort-api-v2.yml index 3d8071e..fd69f38 100644 --- a/topsort-api-v2.yml +++ b/topsort-api-v2.yml @@ -82,13 +82,13 @@ tags: ## Winner (Sponsored Listings) - + ## Autobidding Result - + ## Autobidding Bid - + ## Autobidding Bid Info @@ -336,7 +336,7 @@ paths: amount: 24 qualityScore: 0.1 error: false - - winners: [ ] + - winners: [] error: false 401: $ref: '#/components/responses/UnauthorizedError' @@ -1128,7 +1128,6 @@ components: - error - resultType - AutobiddingBid: description: > Container for the autobidding bid result, similar to auction winner From 406a543013bb8852d89b0df876913b98fa63c61c Mon Sep 17 00:00:00 2001 From: Alexey Stysin Date: Fri, 10 Nov 2023 20:42:47 +0200 Subject: [PATCH 3/4] remove .idea project files --- .gitignore | 1 + .idea/inspectionProfiles/Project_Default.xml | 138 ------------------ .../inspectionProfiles/profiles_settings.xml | 6 - .idea/modules.xml | 8 - .idea/openapi.iml | 8 - 5 files changed, 1 insertion(+), 160 deletions(-) delete mode 100644 .idea/inspectionProfiles/Project_Default.xml delete mode 100644 .idea/inspectionProfiles/profiles_settings.xml delete mode 100644 .idea/modules.xml delete mode 100644 .idea/openapi.iml diff --git a/.gitignore b/.gitignore index 33c581e..920e8f2 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,2 @@ openapitools.json +.idea diff --git a/.idea/inspectionProfiles/Project_Default.xml b/.idea/inspectionProfiles/Project_Default.xml deleted file mode 100644 index cbe3bff..0000000 --- a/.idea/inspectionProfiles/Project_Default.xml +++ /dev/null @@ -1,138 +0,0 @@ - - - - \ No newline at end of file diff --git a/.idea/inspectionProfiles/profiles_settings.xml b/.idea/inspectionProfiles/profiles_settings.xml deleted file mode 100644 index 105ce2d..0000000 --- a/.idea/inspectionProfiles/profiles_settings.xml +++ /dev/null @@ -1,6 +0,0 @@ - - - - \ No newline at end of file diff --git a/.idea/modules.xml b/.idea/modules.xml deleted file mode 100644 index 3b4c6f6..0000000 --- a/.idea/modules.xml +++ /dev/null @@ -1,8 +0,0 @@ - - - - - - - - \ No newline at end of file diff --git a/.idea/openapi.iml b/.idea/openapi.iml deleted file mode 100644 index d0876a7..0000000 --- a/.idea/openapi.iml +++ /dev/null @@ -1,8 +0,0 @@ - - - - - - - - \ No newline at end of file From 9a5c0de94d8c7fa2ed837f2794b54d7eb87b5639 Mon Sep 17 00:00:00 2001 From: Alexey Stysin Date: Fri, 10 Nov 2023 21:02:01 +0200 Subject: [PATCH 4/4] add preview message to the summary of the endpoint --- topsort-api-v2.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/topsort-api-v2.yml b/topsort-api-v2.yml index fd69f38..ec819ee 100644 --- a/topsort-api-v2.yml +++ b/topsort-api-v2.yml @@ -241,7 +241,7 @@ paths: post: tags: - Auctions - summary: Create new autobidding requests + summary: (Preview) Create new autobidding requests operationId: createAutobiddingRequest requestBody: description: |