diff --git a/.github/matcher-actionlint.json b/.github/matcher-actionlint.json new file mode 100644 index 0000000..4613e16 --- /dev/null +++ b/.github/matcher-actionlint.json @@ -0,0 +1,17 @@ +{ + "problemMatcher": [ + { + "owner": "actionlint", + "pattern": [ + { + "regexp": "^(?:\\x1b\\[\\d+m)?(.+?)(?:\\x1b\\[\\d+m)*:(?:\\x1b\\[\\d+m)*(\\d+)(?:\\x1b\\[\\d+m)*:(?:\\x1b\\[\\d+m)*(\\d+)(?:\\x1b\\[\\d+m)*: (?:\\x1b\\[\\d+m)*(.+?)(?:\\x1b\\[\\d+m)* \\[(.+?)\\]$", + "file": 1, + "line": 2, + "column": 3, + "message": 4, + "code": 5 + } + ] + } + ] +} diff --git a/.github/workflows/check-specs.yml b/.github/workflows/check-specs.yml deleted file mode 100644 index 002f11e..0000000 --- a/.github/workflows/check-specs.yml +++ /dev/null @@ -1,37 +0,0 @@ -name: check-specs -on: - pull_request: - branches: - - main -jobs: - check-specs: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v2 - - uses: actions/setup-node@v2 - - name: Cache node modules - id: cache-node - uses: actions/cache@v4 - with: - path: ~/.npm - key: ${{ runner.os }}-node-${{ hashFiles('.github/workflows/check-specs.yml') }} - restore-keys: | - ${{ runner.os }}-node- - - - name: Install Dependencies - run: npm install -g prettier@2.5.1 @openapitools/openapi-generator-cli@2.4.24 - - - name: Check Formatting - run: prettier --check . - - - name: Check Spec (Topsort Endpoints v1) - run: openapi-generator-cli validate -i topsort-api-v1.yml - - - name: Check Spec (Topsort Endpoints v2) - run: openapi-generator-cli validate -i topsort-api-v2.yml - - - name: Check Spec (Catalog CRUD API) - run: openapi-generator-cli validate -i catalog-crud-api.yml - - - name: Check Spec (Catalog Service) - run: openapi-generator-cli validate -i topsort-catalog-service.yml diff --git a/.github/workflows/lint-tools.yml b/.github/workflows/lint-tools.yml new file mode 100644 index 0000000..43f0d34 --- /dev/null +++ b/.github/workflows/lint-tools.yml @@ -0,0 +1,63 @@ +name: Lint +on: + pull_request: + +jobs: + actionlint: + name: Actionlint + runs-on: ubuntu-24.04 + steps: + - uses: actions/checkout@v4 + - name: Install Actionlint + env: + version: "1.7.7" + run: + curl -Ls "https://github.com/rhysd/actionlint/releases/download/v${{ env.version + }}/actionlint_${{ env.version }}_linux_amd64.tar.gz" | sudo tar -x -z -C /usr/local/bin + actionlint + - run: | + echo "::add-matcher::.github/matcher-actionlint.json" + actionlint -color + + prettier: + name: Prettier + runs-on: ubuntu-24.04 + steps: + - uses: actions/checkout@v4 + - run: npx prettier --check . + + vacuum: + name: Vacuum + runs-on: ubuntu-24.04 + steps: + - uses: actions/checkout@v4 + - name: Install Vacuum + env: + version: 0.17.8 + run: + curl -Ls "https://github.com/daveshanley/vacuum/releases/download/v${{ env.version + }}/vacuum_${{ env.version }}_linux_x86_64.tar.gz" | sudo tar -x -z -C /usr/local/bin + vacuum + - run: vacuum lint -d -e -b ./topsort-api-v2.yml + + yamllint: + name: YAMLLint + runs-on: ubuntu-24.04 + steps: + - uses: actions/checkout@v4 + - uses: astral-sh/setup-uv@v6 + - run: uvx yamllint -f github topsort-api-*.yml + + redocly: + name: Redocly + runs-on: ubuntu-24.04 + steps: + - uses: actions/checkout@v4 + - run: npx @redocly/cli lint --format github-actions topsort-api-*.yml + + typos: + name: Check for language typos + runs-on: ubuntu-24.04 + steps: + - uses: actions/checkout@v4 + - uses: crate-ci/typos@v1.35.2 diff --git a/.github/workflows/validate-typos.yml b/.github/workflows/validate-typos.yml deleted file mode 100644 index 6deee02..0000000 --- a/.github/workflows/validate-typos.yml +++ /dev/null @@ -1,11 +0,0 @@ -name: Typos -on: - pull_request: - -jobs: - typos: - name: Check for language typos - runs-on: ubuntu-24.04 - steps: - - uses: actions/checkout@v4 - - uses: crate-ci/typos@v1.29.4 diff --git a/.prettierrc b/.prettierrc deleted file mode 100644 index 0176969..0000000 --- a/.prettierrc +++ /dev/null @@ -1 +0,0 @@ -singleQuote: true diff --git a/.prettierrc.json b/.prettierrc.json new file mode 100644 index 0000000..ac50a21 --- /dev/null +++ b/.prettierrc.json @@ -0,0 +1,4 @@ +{ + "printWidth": 100, + "proseWrap": "always" +} diff --git a/.typos.toml b/.typos.toml deleted file mode 100644 index 037caa6..0000000 --- a/.typos.toml +++ /dev/null @@ -1,2 +0,0 @@ -[default.extend-identifiers] -bneEmHKG2yUe = "bneEmHKG2yUe" diff --git a/.yamllint.yaml b/.yamllint.yaml new file mode 100644 index 0000000..38c68ba --- /dev/null +++ b/.yamllint.yaml @@ -0,0 +1,5 @@ +extends: default + +rules: + document-start: disable + line-length: disable diff --git a/README.md b/README.md index cc56aca..a0c7f41 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,29 @@ # Topsort OpenAPI -Topsort uses the [OpenAPI 3.0.1](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.1.md) specification to [document our APIs](https://docs.topsort.com) and we recommend our clients to use these specifications to generate supported client libraries and server scaffolding. This would provide a consistent and robust developer experience across languages. +Topsort uses the [OpenAPI 3.1.0][openapi] specification to [document our APIs][docs] and we +recommend our clients to use these specifications to generate supported client libraries and server +scaffolding. This would provide a consistent and robust developer experience across languages. + +You can additionally consume the entire Topsort OpenAPI spec available [here][openapi-ts]. + +## Validating the file + +- Use [prettier][prettier] to format the documents: `bunx prettier -w` +- Use [yamllint][yamllint] to validate the documents: `uvx yamllint *.yml` +- Use [vacuum][vacuum] to validate the openapi standard: `vacuum *.yml` +- Use [redocly][redocly] to further validate the openapi standard: `bunx @redocly/cli lint *.yml` +- Use [typos][typos] to fix language typos: `typos .` ## Using the OpenAPI generator -You can find examples on the official [OpenAPI Generator docs](https://openapi-generator.tech/docs/usage#examples). +You can find examples on the official +[OpenAPI Generator docs](https://openapi-generator.tech/docs/usage#examples). + +[openapi]: https://spec.openapis.org/oas/v3.1.0.html +[docs]: https://docs.topsort.com +[openapi-ts]: https://docs.topsort.com/openapi.json +[prettier]: https://prettier.io/ +[yamllint]: https://github.com/adrienverge/yamllint +[vacuum]: https://quobix.com/vacuum/start/ +[redocly]: https://redocly.com/docs/cli/installation +[typos]: https://github.com/crate-ci/typos diff --git a/catalog-crud-api.yml b/catalog-crud-api.yml deleted file mode 100644 index 1507fbd..0000000 --- a/catalog-crud-api.yml +++ /dev/null @@ -1,566 +0,0 @@ -openapi: 3.0.2 -info: - title: Catalog API - version: 0.1.1 - description: Integration API to sync your catalog with Topsort. - license: - name: Apache 2.0 - url: http://www.apache.org/licenses/LICENSE-2.0.html - x-logo: - url: https://assets.website-files.com/61a717c57f45d64e5e24eebf/61ee6ccc3f6a684756ef6dec_logo.svg - backgroundColor: '#fff' - altText: Topsort -servers: - - url: https://central-services.api.sandbox.topsort.ai/public/v1/catalog-search-service - description: Sandbox server -security: - - HTTPBearer: [] -paths: - /catalogs/categories: - get: - tags: - - Categories API - summary: List Categories - operationId: list_categories - parameters: - - $ref: '#/components/parameters/offset' - - $ref: '#/components/parameters/limit' - responses: - '200': - description: The paginated list of categories. - content: - application/json: - schema: - $ref: '#/components/schemas/CategoryPage' - put: - tags: - - Categories API - summary: Upsert Categories - description: > - Creates the categories passed in the body. - If a category with the same ID already exists, the new content will completely replace the previous contents - (i.e. the result is the same as deleting any categories with the IDs that were passed in the request and then creating them from scratch). - operationId: upsert_categories - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/Categories' - required: true - responses: - '204': - description: The categories were stored successfully. - '422': - description: Validation Error. - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' - security: - - HTTPBearer: [] - delete: - tags: - - Categories API - summary: Delete Categories - operationId: delete_categories_by_id - responses: - '204': - description: The categories with provided IDs were deleted. - '404': - description: One or more provided category IDs were not present. - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPNotFoundError' - # '409': - # description: One or more provided category IDs are associated to one or more products. - # content: - # application/json: - # schema: - # $ref: '#/components/schemas/HTTPConflictError' - security: - - HTTPBearer: [] - /catalogs/categories/{categoryId}: - get: - tags: - - Categories API - summary: Get Category - operationId: get_category_by_id - parameters: - - required: true - schema: - title: Category ID - description: The ID of the category to fetch. - type: string - name: categoryId - in: path - responses: - '200': - description: The requested category. - content: - application/json: - schema: - $ref: '#/components/schemas/Category' - '404': - description: No category exists with the provided ID. - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPNotFoundError' - security: - - HTTPBearer: [] - /catalogs/products: - get: - tags: - - Products API - summary: List Products - operationId: list_products - parameters: - - $ref: '#/components/parameters/offset' - - $ref: '#/components/parameters/limit' - responses: - '200': - description: The paginated list of products. - content: - application/json: - schema: - $ref: '#/components/schemas/ProductPage' - put: - tags: - - Products API - summary: Upsert Products - description: > - Creates the products passed in the body. - If a product with the same ID already exists, the new content will completely replace the previous contents - (i.e. the result is the same as deleting any products with the IDs that were passed in the request and then creating them from scratch). - operationId: upsert_products - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/Products' - required: true - responses: - '204': - description: The products were stored successfully. - '422': - description: Validation Error. - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' - security: - - HTTPBearer: [] - delete: - tags: - - Products API - summary: Delete Products - operationId: delete_products_by_id - responses: - '204': - description: The products with provided IDs were deleted. - '404': - description: One or more provided product IDs were not present. - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPNotFoundError' - /catalogs/products/{productId}: - get: - tags: - - Products API - summary: Get Product - operationId: get_product_by_id - parameters: - - required: true - schema: - title: Product ID - description: The ID of the product to fetch. - type: string - name: productId - in: path - responses: - '200': - description: The requested product. - content: - application/json: - schema: - $ref: '#/components/schemas/Product' - '404': - description: No product exists with the provided ID. - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPNotFoundError' - security: - - HTTPBearer: [] - /catalogs/vendors: - get: - tags: - - Vendors API - summary: List Vendors - operationId: list_vendors - parameters: - - $ref: '#/components/parameters/offset' - - $ref: '#/components/parameters/limit' - responses: - '200': - description: The paginated list of vendors. - content: - application/json: - schema: - $ref: '#/components/schemas/VendorPage' - put: - tags: - - Vendors API - summary: Upsert Vendors - description: > - Creates the vendors passed in the body. - If a vendor with the same ID already exists, the new content will completely replace the previous contents - (i.e. the result is the same as deleting any vendors with the IDs that were passed in the request and then creating them from scratch). - operationId: upsert_vendors - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/Vendors' - required: true - responses: - '204': - description: The vendors were stored successfully. - '422': - description: Validation Error. - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' - security: - - HTTPBearer: [] - delete: - tags: - - Vendors API - summary: Delete Vendors - operationId: delete_vendors_by_id - responses: - '204': - description: The vendors with provided IDs were deleted. - '404': - description: One or more provided vendors IDs were not present. - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPNotFoundError' - /catalogs/vendors/{vendorId}: - get: - tags: - - Vendors API - summary: Get Vendor - operationId: get_vendor_by_id - parameters: - - required: true - schema: - title: Vendor ID - description: The ID of the vendor to fetch. - type: string - name: vendorId - in: path - responses: - '200': - description: The requested vendor. - content: - application/json: - schema: - $ref: '#/components/schemas/Vendor' - '404': - description: No vendor exists with the provided ID. - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPNotFoundError' - security: - - HTTPBearer: [] -components: - schemas: - Category: - type: object - properties: - id: - description: > - The category ID. - If there is no ID for categories in the marketplace, - this can be the category name as long as it is unique. - type: string - minLength: 1 - example: ahEDqV5uhjj8 - name: - description: The category name. - type: string - minLength: 1 - example: Beers/Belgian - parentId: - description: > - The ID of the parent category. - This model assumes each category can at most one parent category. - In this example, `bneEmHKG2yUe` could be a reference to the `Beers` category. - type: string - minLength: 1 - example: bneEmHKG2yUe - required: - - id - - name - Categories: - type: object - properties: - categories: - description: The categories to create or substitute. - type: array - items: - $ref: '#/components/schemas/Category' - minLength: 1 - required: - - categories - CategoryPage: - title: Category page - type: object - properties: - next: - $ref: '#/components/schemas/Next' - response: - description: Array of categories. - type: array - items: - $ref: '#/components/schemas/Category' - required: - - next - - response - Next: - type: object - nullable: true - example: null - properties: - offset: - title: Offset - description: How many items to skip from the beginning of the list. - type: integer - format: int32 - limit: - title: Limit - description: How many items to return. - type: integer - format: int32 - Product: - type: object - properties: - id: - description: The product ID. - type: string - minLength: 1 - example: eyGqR4YQgBJa - name: - description: The product name. - type: string - minLength: 1 - example: Delirium Tremens Beer Bottle 330cc x6 - description: - description: The product description. - type: string - minLength: 1 - example: > - Named as "Best Beer in the World" in 2008 at the World Beer Championships in Chicago, Illinois. - vendors: - description: The vendor IDs. - type: array - items: - type: string - minLength: 1 - minLength: 1 - example: - - 9SiwYqqL8vdG - categories: - description: The category IDs. - type: array - items: - type: string - minLength: 1 - minLength: 1 - example: - - ahEDqV5uhjj8 - imageURL: - description: > - The product image URL. - Its size should be between 250x250 and 600x600 pixels. - This is recommended in case the Topsort UI will be used to manage campaigns. - type: string - format: uri - example: https://r.btcdn.co/r/eyJzaG9wX2lkIjozMzU4LCJnIjoiMjYweCJ9/1759e16e6314a24/669830-Cerveza_Delirium_Tremens_Botella_330cc_x6.png - price: - description: The product price in the configured currency. - type: number - format: double - minimum: 0.0 - exclusiveMinimum: true - example: 18.99 - brand: - description: The product brand information. - type: object - properties: - id: - type: string - description: The brand ID. - example: es5086vyV - name: - type: string - description: The brand name. - example: Delirium - required: - - id - - name - required: - - id - - name - - description - - vendors - - categories - - brand - - price - - imageURL - Products: - type: object - properties: - products: - description: The products to create or substitute. - type: array - items: - $ref: '#/components/schemas/Product' - minLength: 1 - required: - - products - ProductPage: - title: Product page - type: object - properties: - next: - $ref: '#/components/schemas/Next' - response: - description: Array of products. - type: array - items: - $ref: '#/components/schemas/Product' - required: - - next - - response - Vendor: - title: Vendor - type: object - properties: - id: - description: > - The vendor ID. - If there is no ID for vendors in the marketplace, - this can be the vendor name as long as it is unique. - type: string - minLength: 1 - example: 9SiwYqqL8vdG - name: - description: The vendor name. - type: string - minLength: 1 - example: Huyghe Brewery - imageURL: - description: > - The vendor logo. - Its size should be between 250x250 and 600x600 pixels. - This is recommended in case the Topsort UI will be used to manage campaigns. - type: string - format: uri - example: https://r.btcdn.co/r/eyJzaG9wX2lkIjozMzU4LCJnIjoiMjYweCJ9/1759e16e6314a24/669830-Cerveza_Delirium_Tremens_Botella_330cc_x6.png - required: - - id - - name - Vendors: - type: object - properties: - vendors: - description: The vendors to create or substitute. - type: array - items: - $ref: '#/components/schemas/Vendor' - minLength: 1 - required: - - vendors - VendorPage: - title: Vendor page - type: object - properties: - next: - $ref: '#/components/schemas/Next' - response: - description: Array of vendors. - type: array - items: - $ref: '#/components/schemas/Vendor' - required: - - next - - response - HTTPNotFoundError: - title: HTTP Not Found Error - required: - - msg - type: object - properties: - msg: - title: Message - type: string - HTTPValidationError: - title: HTTP Validation Error - required: - - msg - type: object - properties: - msg: - title: Message - type: string - example: Entity not found. - securitySchemes: - HTTPBearer: - type: http - scheme: bearer - parameters: - offset: - in: query - name: offset - schema: - type: integer - format: int32 - description: > - An integer indicating how many items to skip from the beginning of the list of entities. - You may provide the value returned in the `next` field from the response of a previous page. - If not present, values will be returned from the start. - limit: - in: query - name: limit - schema: - type: integer - format: int32 - maximum: 100 - description: > - An integer indicating how many items will be returned taking the `offset` into account. - You may provide the value returned in the `next` field from the response of a previous page. -tags: - - name: Categories API - description: 'CRUD API to manage category entities' - - name: Products API - description: 'CRUD API to manage product entities' - - name: Vendors API - description: 'CRUD API to manage vendor entities' - - name: Models - x-displayName: Catalog Models - description: | - ## Category - - - ## Product - - - ## Vendor - diff --git a/topsort-api-v1.yml b/topsort-api-v1.yml index 37a845d..c29fa12 100644 --- a/topsort-api-v1.yml +++ b/topsort-api-v1.yml @@ -1,6 +1,7 @@ openapi: 3.0.1 info: title: Topsort Endpoints v1 API Reference + description: The OpenAPI specifciation for Topsort v1 endpoints contact: email: wicha@topsort.com license: @@ -8,7 +9,7 @@ info: url: http://www.apache.org/licenses/LICENSE-2.0.html x-logo: url: https://assets.topsort.com/Topsort_logo_icon_dark.svg - backgroundColor: '#fff' + backgroundColor: "#fff" altText: Topsort version: 1.0.1 @@ -85,28 +86,29 @@ paths: operationId: createAuction requestBody: description: > - The information describing what will be auctioned. - Topsort will run an auction for each slot type, for which products' bids will compete against each other. - The products that will participate are included in the request. + The information describing what will be auctioned. Topsort will run an auction for each + slot type, for which products' bids will compete against each other. The products that + will participate are included in the request. content: application/json: schema: - $ref: '#/components/schemas/AuctionRequest' + $ref: "#/components/schemas/AuctionRequest" required: true responses: 201: description: - "The auction results. The list of Winner objects will contain at most slots entries. - It may contain fewer or no entries at all if there aren't enough products with usable bids. - Bids become unusable if their campaign budget is exhausted, the bid is disqualified to preserve spend pacing, etc." + "The auction results. The list of Winner objects will contain at most slots entries. It + may contain fewer or no entries at all if there aren't enough products with usable bids. + Bids become unusable if their campaign budget is exhausted, the bid is disqualified to + preserve spend pacing, etc." content: application/json: schema: - $ref: '#/components/schemas/Auction' + $ref: "#/components/schemas/Auction" 400: - $ref: '#/components/responses/BadRequest' + $ref: "#/components/responses/BadRequest" 401: - $ref: '#/components/responses/UnauthorizedError' + $ref: "#/components/responses/UnauthorizedError" /events: post: @@ -116,30 +118,33 @@ paths: summary: Report an event operationId: reportEvent requestBody: - description: 'Use the `/events` endpoint to notify Topsort about significant consumer interactions on the e-commerce site: impressions -- product links become visible to the consumer; clicks -- the consumer clicks on a product link; and purchases -- the consumer buys some products.' + description: + "Use the `/events` endpoint to notify Topsort about significant consumer interactions on + the e-commerce site: impressions -- product links become visible to the consumer; clicks + -- the consumer clicks on a product link; and purchases -- the consumer buys some + products." content: application/json: schema: - $ref: '#/components/schemas/Event' + $ref: "#/components/schemas/Event" required: true responses: 200: description: - 'An object containing the markeplace ID for the event and the Topsort ID for the same event. - Logging this can facilitate debugging. - The field name for the TopsortID will be "impressionID", "clickId" or "purchaseId" - depending on the event in the request.' + An object containing the marketplace ID for the event and the Topsort ID for the same + event. Logging this can facilitate debugging. The field name for the TopsortID will be + "impressionID", "clickId" or "purchaseId" depending on the event in the request. content: application/json: schema: oneOf: - - $ref: '#/components/schemas/ImpressionsResponse' - - $ref: '#/components/schemas/ClickResponse' - - $ref: '#/components/schemas/PurchaseResponse' + - $ref: "#/components/schemas/ImpressionsResponse" + - $ref: "#/components/schemas/ClickResponse" + - $ref: "#/components/schemas/PurchaseResponse" 401: - $ref: '#/components/responses/UnauthorizedError' + $ref: "#/components/responses/UnauthorizedError" 400: - $ref: '#/components/responses/BadRequest' + $ref: "#/components/responses/BadRequest" components: responses: @@ -150,7 +155,7 @@ components: content: application/json: schema: - $ref: '#/components/schemas/Error' + $ref: "#/components/schemas/Error" schemas: AuctionRequest: @@ -160,17 +165,18 @@ components: - products properties: slots: - $ref: '#/components/schemas/Slots' + $ref: "#/components/schemas/Slots" products: type: array - description: An array of objects, each describing a product that should participate in the auction. + description: + An array of objects, each describing a product that should participate in the auction. items: - $ref: '#/components/schemas/Product' + $ref: "#/components/schemas/Product" minItems: 1 session: - $ref: '#/components/schemas/Session' + $ref: "#/components/schemas/Session" geoTargeting: - $ref: '#/components/schemas/GeoTargeting' + $ref: "#/components/schemas/GeoTargeting" example: slots: listings: 2 @@ -193,15 +199,17 @@ components: properties: auctionId: type: string - description: Topsort assigned ID for the auction. Should be used in reporting impressions, clicks and purchases. + description: + Topsort assigned ID for the auction. Should be used in reporting impressions, + clicks and purchases. example: AKFU78 winners: type: array items: - $ref: '#/components/schemas/Winner' + $ref: "#/components/schemas/Winner" description: - 'Array of winner objects in order from highest to lowest bid. - May be empty if there were no qualifying bids.' + "Array of winner objects in order from highest to lowest bid. May be empty if + there were no qualifying bids." GeoTargeting: type: object @@ -223,17 +231,20 @@ components: rank: type: integer description: > - Where the product's bid ranked in the auction. - One-based, so the product with rank 1 won the auction. - In an auction response, the winners array is sorted so rank will match the entry's index. + Where the product's bid ranked in the auction. One-based, so the product with rank 1 won + the auction. In an auction response, the winners array is sorted so rank will match the + entry's index. minimum: 1 productId: type: string - description: The marketplace's ID for the product. It will match the ID for a product in the request's products array. + description: + The marketplace's ID for the product. It will match the ID for a product in the + request's products array. example: pSA0238 winnerType: type: string - description: The type of the winning bid, depending on the campaign. It can be product or vendor. + description: + The type of the winning bid, depending on the campaign. It can be product or vendor. enum: - product - vendor @@ -267,7 +278,9 @@ components: name: Product Session: - description: The Session object allows correlating user activity during a session whether or not they are actually logged in. + description: + The Session object allows correlating user activity during a session whether or not they are + actually logged in. required: - sessionId type: object @@ -276,19 +289,13 @@ components: description: > Long-lived token identifying the customer interacting with the marketplace. - If your users are always logged in you may use a hash of your customer ID. - If your users may interact with your app or site while logged out we recommend generating a random identifier (UUIDv4) on first load and store it on local storage (cookie, local storage, etc) and let it live for at least a year. + If your users are always logged in you may use a hash of your customer ID. If your users + may interact with your app or site while logged out we recommend generating a random + identifier (UUIDv4) on first load and store it on local storage (cookie, local storage, + etc) and let it live for at least a year. type: string minLength: 1 example: ebeaf802-6d0a-41a3-ae59-661887c4f6cb - # consumerId: - # description: > - # Optional ID identifying the user, this field is required in case your marketplace wants to do cross-device attribution. - # - # Instead of sending us the exact same user ID you are storing in your systems we recommend you to send us a hash of the user ID (SHA1, SHA512, etc). - # This field is needed for cross-device attribution. - # type: string - # example: cid_86hkz2p3171joer80pdkltu7n Placement: type: object @@ -307,7 +314,10 @@ components: example: position_1 ClickEvent: - description: ClickEvents are sent to Topsort when the consumer has clicked on an impression. Topsort charges the vendor and pays the marketplace for clicks on impressions in promoted placements on the e-commerce site. + description: + ClickEvents are sent to Topsort when the consumer has clicked on an impression. Topsort + charges the vendor and pays the marketplace for clicks on impressions in promoted placements + on the e-commerce site. type: object required: - eventType @@ -320,9 +330,9 @@ components: enum: - Click session: - $ref: '#/components/schemas/Session' + $ref: "#/components/schemas/Session" placement: - $ref: '#/components/schemas/Placement' + $ref: "#/components/schemas/Placement" productId: type: string description: The product that was clicked. @@ -330,7 +340,8 @@ components: example: p_SA0238 auctionId: type: string - description: Required for promoted products. Must be the ID for the auction the product won. + description: + Required for promoted products. Must be the ID for the auction the product won. minLength: 1 example: AKFU78 id: @@ -342,7 +353,7 @@ components: type: string format: date-time description: RFC3339 formatted timestamp including UTC offset - example: '2009-01-01T12:59:59-05:00' + example: "2009-01-01T12:59:59-05:00" resolvedBidId: type: string minLength: 1 @@ -358,9 +369,11 @@ components: ImpressionEvent: description: > - A product has become visible to the consumer. - In case you cannot send the impression when the product is visible, send us an impression event when the product was rendered in the HTML or if that's also not possible when your API returns the results. - It is important to select the most specific event so that your vendors have more accurate CTR metrics, which allow them to better predict their campaigns. + A product has become visible to the consumer. In case you cannot send the impression when + the product is visible, send us an impression event when the product was rendered in the + HTML or if that's also not possible when your API returns the results. It is important to + select the most specific event so that your vendors have more accurate CTR metrics, which + allow them to better predict their campaigns. type: object required: - eventType @@ -373,12 +386,12 @@ components: enum: - Impression session: - $ref: '#/components/schemas/Session' + $ref: "#/components/schemas/Session" impressions: type: array minItems: 1 items: - $ref: '#/components/schemas/Impression' + $ref: "#/components/schemas/Impression" example: - resolvedBidId: WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0= id: 234f678-f90c @@ -393,7 +406,7 @@ components: type: string format: date-time description: RFC3339 formatted timestamp including UTC offset - example: '2022-01-23T12:34:56-05:00' + example: "2022-01-23T12:34:56-05:00" Impression: type: object @@ -401,14 +414,15 @@ components: - placement properties: placement: - $ref: '#/components/schemas/Placement' + $ref: "#/components/schemas/Placement" productId: type: string description: The product that was rendered. example: p_SA0238 auctionId: type: string - description: Required for promoted products. Must be the ID for the auction the product won. + description: + Required for promoted products. Must be the ID for the auction the product won. minLength: 1 example: AKFU78 id: @@ -437,7 +451,7 @@ components: enum: - Purchase session: - $ref: '#/components/schemas/Session' + $ref: "#/components/schemas/Session" id: type: string description: The marketplace assigned ID for the order. @@ -446,14 +460,14 @@ components: purchasedAt: type: string description: RFC3339 formatted timestamp including UTC offset - example: '2021-10-12T07:20:50.52Z' + example: "2021-10-12T07:20:50.52Z" format: date-time items: type: array description: Items purchased. minItems: 1 items: - $ref: '#/components/schemas/PurchaseItem' + $ref: "#/components/schemas/PurchaseItem" PurchaseItem: type: object @@ -468,7 +482,9 @@ components: example: p_SA0238 auctionId: type: string - description: If known, the product's auction ID if the consumer clicked on a promoted link before purchasing. + description: + If known, the product's auction ID if the consumer clicked on a promoted link before + purchasing. minLength: 1 example: AKFU78 quantity: @@ -480,7 +496,9 @@ components: unitPrice: type: integer minimum: 1 - description: The price of a single item in minor currency units. For example, in the US (currency code "USD") the unit price is specified in cents. + description: + The price of a single item in minor currency units. For example, in the US (currency + code "USD") the unit price is specified in cents. example: 1295 resolvedBidId: type: string @@ -493,9 +511,9 @@ components: Event: oneOf: - - $ref: '#/components/schemas/ImpressionEvent' - - $ref: '#/components/schemas/ClickEvent' - - $ref: '#/components/schemas/PurchaseEvent' + - $ref: "#/components/schemas/ImpressionEvent" + - $ref: "#/components/schemas/ClickEvent" + - $ref: "#/components/schemas/PurchaseEvent" ImpressionResponse: type: object @@ -518,7 +536,7 @@ components: type: array description: The collection of all impressions that were processed correctly. items: - $ref: '#/components/schemas/ImpressionResponse' + $ref: "#/components/schemas/ImpressionResponse" example: impressions: - impressionId: 70ed4d78-34aa-42c7-b6e2-6a670568b6e3 @@ -555,10 +573,9 @@ components: Slots: description: - 'The Slots object specifies how many auctions winners should be - returned for each promotion type. The promotion types depend on - the marketplace configuration. For sponsored listings, use the - "listings" key.' + 'The Slots object specifies how many auctions winners should be returned for each promotion + type. The promotion types depend on the marketplace configuration. For sponsored listings, + use the "listings" key.' type: object properties: listings: @@ -604,8 +621,9 @@ components: message: type: string description: > - Human-readable explanation of or details about the error. - The string for a given error may change over time; code should not parse or dispatch based on particular values for this field. + Human-readable explanation of or details about the error. The string for a given error + may change over time; code should not parse or dispatch based on particular values for + this field. securitySchemes: BearerAuth: diff --git a/topsort-api-v2.yml b/topsort-api-v2.yml index ee97b5c..13e5f23 100644 --- a/topsort-api-v2.yml +++ b/topsort-api-v2.yml @@ -1,9 +1,12 @@ -openapi: 3.0.1 +openapi: 3.1.0 info: title: Topsort Endpoints v2 API Reference - description: >- - In order for a storefront to be able to run auctions in Topsort and report auction-related events back to Topsort, + description: > + In order for a storefront to be able to run auctions in Topsort and report auction-related + events back to Topsort, + both the `/v2/auctions` and `/v2/events` endpoints must be integrated. + Below are the endpoint and model definitions for each. contact: email: wicha@topsort.com @@ -12,118 +15,47 @@ info: url: http://www.apache.org/licenses/LICENSE-2.0.html x-logo: url: https://assets.topsort.com/Topsort_logo_icon_dark.svg - backgroundColor: '#fff' + backgroundColor: "#fff" altText: Topsort version: 2.0.0 - servers: - url: https://api.topsort.com description: Base API URL - tags: - name: Auctions description: An auction determines which products should be promoted based on the vendors' bids. - name: Events - description: | - **The specification details, particularly around placement data, may change in the short term.** - **If this is not acceptable for your integration, please use [Events V1](https://docs.topsort.com/reference/reportevent) as an alternative.** + description: > + **The specification details, particularly around placement data, may change in the short + term.** + + **If this is not acceptable for your integration, please use [Events + V1](https://docs.topsort.com/reference/reportevent) as an alternative.** Significant consumer interactions on the marketplace app. - name: Toptimize - description: | - An out-of-the-box solution for prediction, ranking, retrieval, and other elements of ad selection. - - name: Models - x-displayName: All Models - description: | - ## AssetSource - - - ## Auction (Banners) - - - ## Auction (Sponsored Listings) - - - ## Auction Result (Banners) - - - ## Auction Result (Sponsored Listings) - - - ## Category - - - ## Category Disjunction - - - ## Click - - - ## Error - - - ## Events Request - - - ## Geotargeting - - - ## Impression - - - ## Products - - - ## Purchase - - - ## Purchase Item - - - ## Winner (Banners) - - - ## Winner (Sponsored Listings) - - - ## Page - - - ## RankingRequest - - - ## PredictionRequest - - - ## RankingResult - - - ## PredictionResult - - - ## RankingWinner - - - ## Interaction Object - - + description: > + An out-of-the-box solution for prediction, ranking, retrieval, and other elements of ad + selection. security: - - BearerAuth: [] - + - HTTPBearer: [] paths: /v2/auctions: post: tags: - Auctions summary: Create auctions - description: | - Use the `/auctions` endpoint to create auctions. Each batch of auction requests can be a combination of - sponsored listing auctions and banner auctions. Each auction type has a unique body schemas. + description: > + Use the `/auctions` endpoint to create auctions. Each batch of auction requests can be a + combination of sponsored listing auctions and banner auctions. Each auction type has a + unique body schemas. operationId: createAuctions requestBody: - description: | + description: > The information describing what will be auctioned. - Topsort will run an auction for each batched auction request, for which products' bids will compete against each other. + + Topsort will run an auction for each batched auction request, for which products' bids + will compete against each other. content: application/json: schema: @@ -132,46 +64,18 @@ paths: auctions: type: array items: - $ref: '#/components/schemas/AuctionRequest' + $ref: "#/components/schemas/AuctionRequest" minItems: 1 maxItems: 5 - required: - - auctions - example: - auctions: - - type: listings - slots: 1 - category: - disjunctions: - - - c_large - - c_medium - - 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: + "201": description: > - The auction results. - The list of winners will contain at most `slots` entries per auction. - It may contain fewer or no entries at all if there aren't enough products with usable bids, that is, - a bid amount greater than the reserve price and belonging to a campaign with enough remaining budget. - Bids become unusable if campaign budget is exhausted, the bid is disqualified to preserve spend pacing, etc. + The auction results. The list of winners will contain at most `slots` entries per + auction. It may contain fewer or no entries at all if there aren't enough products with + usable bids, that is, a bid amount greater than the reserve price and belonging to a + campaign with enough remaining budget. Bids become unusable if campaign budget is + exhausted, the bid is disqualified to preserve spend pacing, etc. content: application/json: schema: @@ -180,47 +84,49 @@ paths: results: type: array items: - $ref: '#/components/schemas/AuctionResult' + $ref: "#/components/schemas/AuctionResult" minItems: 1 maxItems: 5 required: - results - example: - results: - - winners: - - rank: 1 - type: product - id: p_Mfk11 - resolvedBidId: WyJiX01mazExIiwiMTJhNTU4MjgtOGVhZC00Mjk5LTMyNjYtY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0== - campaignId: 82588593-85c5-47c0-b125-07e315b7f2b3 - error: false - - winners: - - rank: 1 - type: product - id: p_Mfk15 - resolvedBidId: WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0= - campaignId: 4bcc6093-f367-4df2-aa1b-7c1674dd6441 - - rank: 2 - type: product - id: p_PJbnN - resolvedBidId: WyJlX1BKYm5OIiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0= - campaignId: a72e4e43-55b5-4d08-81bb-cbb57df59c72 - error: false - - winners: - - rank: 1 - type: product - id: p_PJbnN - resolvedBidId: WyJlX1BKYm5OIiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwiYmFubmVyQWRzIiwiZGVmYXVsdCIsIiJd - campaignId: 1156ef4e-0109-4190-ac97-4436c82358d2 - asset: - - url: https://topsort.cdnprovider.com/lhs-banner-image-for-p_PJbnN-1x.png - error: false - - winners: [] - error: false - 400: - $ref: '#/components/responses/BadRequest' - 401: - $ref: '#/components/responses/UnauthorizedError' + examples: + - results: + - winners: + - rank: 1 + type: product + id: p_Mfk11 + resolvedBidId: WyJiX01mazExIiwiMTJhNTU4MjgtOGVhZC00Mjk5LTMyNjYtY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0== + campaignId: 82588593-85c5-47c0-b125-07e315b7f2b3 + error: false + - results: + - winners: + - rank: 1 + type: product + id: p_Mfk15 + resolvedBidId: WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0= + campaignId: 4bcc6093-f367-4df2-aa1b-7c1674dd6441 + - rank: 2 + type: product + id: p_PJbnN + resolvedBidId: WyJlX1BKYm5OIiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0= + campaignId: a72e4e43-55b5-4d08-81bb-cbb57df59c72 + error: false + - winners: + - rank: 1 + type: product + id: p_PJbnN + resolvedBidId: WyJlX1BKYm5OIiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwiYmFubmVyQWRzIiwiZGVmYXVsdCIsIiJd + campaignId: 1156ef4e-0109-4190-ac97-4436c82358d2 + asset: + - url: https://topsort.cdnprovider.com/lhs-banner-image-for-p_PJbnN-1x.png + error: false + - results: + - winners: [] + error: false + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/UnauthorizedError" /v2/auctions/sponsored-brand: post: tags: @@ -228,9 +134,11 @@ paths: summary: Create sponsored brand auctions operationId: createSponsoredBrandAuctions requestBody: - description: | + description: > The information describing what will be auctioned. - Topsort will run an auction for each batched auction request, for which products bids will compete against each other. + + Topsort will run an auction for each batched auction request, for which products bids will + compete against each other. content: application/json: schema: @@ -239,20 +147,20 @@ paths: auctions: type: array items: - $ref: '#/components/schemas/SponsoredBrandAuctionRequest' + $ref: "#/components/schemas/SponsoredBrandAuctionRequest" minItems: 1 maxItems: 5 required: - auctions required: true responses: - 201: + "201": description: > - The auction results. - The list of winners will contain at most `winners` entries per auction. - It may contain fewer or no entries at all if there aren't enough products with usable bids, that is, - a bid amount greater than the reserve price and belonging to a campaign with enough remaining budget. - Bids become unusable if campaign budget is exhausted, the bid is disqualified to preserve spend pacing, etc. + The auction results. The list of winners will contain at most `winners` entries per + auction. It may contain fewer or no entries at all if there aren't enough products with + usable bids, that is, a bid amount greater than the reserve price and belonging to a + campaign with enough remaining budget. Bids become unusable if campaign budget is + exhausted, the bid is disqualified to preserve spend pacing, etc. content: application/json: schema: @@ -261,30 +169,32 @@ paths: results: type: array items: - $ref: '#/components/schemas/SponsoredBrandAuctionResult' + $ref: "#/components/schemas/SponsoredBrandAuctionResult" minItems: 1 maxItems: 5 required: - results - 400: - $ref: '#/components/responses/BadRequest' - 401: - $ref: '#/components/responses/UnauthorizedError' + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/UnauthorizedError" /v2/auctions/travel: post: tags: - Auctions summary: Create travel auctions description: - Use the `/auctions/travel` endpoint to create batch auctions for sponsored travel listings. We support - two types of sponsored travel listings, hotels and flights. Each batch of auction requests can be a combination - of sponsored hotel and flight listing auctions. Each auction type has a unique body schemas. + Use the `/auctions/travel` endpoint to create batch auctions for sponsored travel listings. + We support two types of sponsored travel listings, hotels and flights. Each batch of auction + requests can be a combination of sponsored hotel and flight listing auctions. Each auction + type has a unique body schemas. operationId: createTravelAuctions requestBody: - description: | + description: > The information describing what will be auctioned. - Topsort will run an auction for each batched auction request, for which travel products' bids will compete - against each other. + + Topsort will run an auction for each batched auction request, for which travel products' + bids will compete against each other. content: application/json: schema: @@ -293,51 +203,51 @@ paths: auctions: type: array items: - $ref: '#/components/schemas/TravelAuctionRequest' + $ref: "#/components/schemas/TravelAuctionRequest" minItems: 1 maxItems: 5 required: - auctions - example: - auctions: - - type: hotels - slots: 2 - products: - - id: hotel-1 - qualityScore: 0.7 - - id: hotel-2 - category: - id: hotel-boutique - travelContext: - travelStartDate: 2025-01-01 - travelEndDate: 2025-01-15 - site: argentina - passengers: 2 - travelerType: couple - - type: flights - slots: 2 - products: - - id: 'L0_SAO-ORL' - variationID: '001' - price: 1500 - qualityScore: 0.7 - - id: 'L0_SAO-ORL' - variationID: '002' - price: 2000 - travelContext: - site: argentina - passengers: 2 - route: SAO-ORL - flightType: one-way + examples: + - auctions: + - type: hotels + slots: 2 + products: + - id: hotel-1 + qualityScore: 0.7 + - id: hotel-2 + category: + id: hotel-boutique + travelContext: + travelStartDate: 2025-01-01 + travelEndDate: 2025-01-15 + site: argentina + passengers: 2 + travelerType: couple + - type: flights + slots: 2 + products: + - id: L0_SAO-ORL + variationID: "001" + price: 1500 + qualityScore: 0.7 + - id: L0_SAO-ORL + variationID: "002" + price: 2000 + travelContext: + site: argentina + passengers: 2 + route: SAO-ORL + flightType: one-way required: true responses: - 201: + "201": description: > - The auction results. - The list of winners will contain at most `winners` entries per auction. - It may contain fewer or no entries at all if there aren't enough products with usable bids, that is, - a bid amount greater than the reserve price and belonging to a campaign with enough remaining budget. - Bids become unusable if campaign budget is exhausted, the bid is disqualified to preserve spend pacing, etc. + The auction results. The list of winners will contain at most `winners` entries per + auction. It may contain fewer or no entries at all if there aren't enough products with + usable bids, that is, a bid amount greater than the reserve price and belonging to a + campaign with enough remaining budget. Bids become unusable if campaign budget is + exhausted, the bid is disqualified to preserve spend pacing, etc. content: application/json: schema: @@ -346,12 +256,12 @@ paths: results: type: array items: - $ref: '#/components/schemas/TravelAuctionResult' + $ref: "#/components/schemas/TravelAuctionResult" minItems: 1 maxItems: 5 required: - results - example: + examples: - results: - resultType: hotels winners: @@ -369,64 +279,77 @@ paths: id: L0_SAO-ORL resolvedBidId: ChAKf-N45Vq3LOTEGcW9VDhKHjADk3_zCXx8db-XZsyiwM2HIjADk4Lr_X0_b9Xw_uKHgyRZKhUKCTHQCTHrrh7 campaignId: 8ab7b29e-1934-4ec9-ad87-60c285bc7f38 - variationID: '002' + variationID: "002" - rank: 2 id: L0_SAO-ORL resolvedBidId: ChAGg-P56Wu4MRUEHdX8VEfLHkBEk4_aEXz9fb-YZtxjwN3IJkBEk5Ms_W2_c8Yx_vZJhzSXKlVLDUJQDUJssl8 campaignId: cb8ed0a7-0ecf-4ffb-a863-022f862649ec - variationID: '001' - 400: - $ref: '#/components/responses/BadRequest' - 401: - $ref: '#/components/responses/UnauthorizedError' + variationID: "001" + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/UnauthorizedError" /v2/events: post: tags: - Events summary: Report events - description: | + description: > Use the `/events` endpoint to report user interactions and activity in on a marketplace: + - **Impressions** — a user viewed an asset. + - **Clicks** — a user clicked on an asset. + - **Purchases** — a user created an order. + - **Pageviews** — a user visited a page. - Interactions require either a `resolvedBidId`, for sponsored events coming from the `/v2/auctions` response, - or an `entity` that describes the entity that was interacted with, in the case of organic or non-sponsored events. + Interactions require either a `resolvedBidId`, for sponsored events coming from the + `/v2/auctions` response, + + or an `entity` that describes the entity that was interacted with, in the case of organic or + non-sponsored events. + + For analytics purposes, you can use the `placement` field to differentiate different + listings or banners. - For analytics purposes, you can use the `placement` field to differentiate different listings or banners. - For example, on a product page with a carousel of products, you can track impressions and clicks related to the carousel - by including `/carousel` at the end of the `path` field in the `placement` object. This allows you to monitor - the performance of carousel products in the [Data Room](https://docs.topsort.com/knowledge-base/analytics/data-room/). + For example, on a product page with a carousel of products, you can track impressions and + clicks related to the carousel + by including `/carousel` at the end of the `path` field in the `placement` object. This + allows you to monitor + + the performance of carousel products in the [Data + Room](https://docs.topsort.com/knowledge-base/analytics/data-room/). operationId: reportEvents requestBody: content: application/json: schema: - $ref: '#/components/schemas/EventsRequest' + $ref: "#/components/schemas/EventsRequest" required: true responses: - 204: + "204": description: All events were reported successfully. - 401: - $ref: '#/components/responses/UnauthorizedError' - 400: - $ref: '#/components/responses/BadRequest' + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/UnauthorizedError" /v2/events/beta/link-users: post: tags: - Events - summary: '[Beta] Report Link Users' - description: | + summary: "[Beta] Report Link Users" + description: > Use the `/events/beta/link-users` endpoint to report to Topsort linked opaque user IDs. - This endpoint allows linking two opaque user IDs for attribution purposes. The `from` field represents the - original opaque user ID, and the `to` field represents the target opaque user ID to be linked. The request - will fail if the `from` and `to` opaque user IDs are the same. + This endpoint allows linking two opaque user IDs for attribution purposes. The `from` field + represents the original opaque user ID, and the `to` field represents the target opaque user + ID to be linked. The request will fail if the `from` and `to` opaque user IDs are the same. Contact your sales representative to gain access to this endpoint and start using it. - x-beta: 'true' + x-beta: "true" operationId: linkUsers requestBody: content: @@ -447,35 +370,39 @@ paths: required: - from - to - example: - from: 'user123' - to: 'user456' + examples: + - from: user123 + to: user456 required: true responses: - 204: + "204": description: Users account link was reported successfully. - 401: - $ref: '#/components/responses/UnauthorizedError' - 400: - $ref: '#/components/responses/BadRequest' + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/UnauthorizedError" /toptimize/v1/rank: post: tags: - Toptimize - summary: '[Beta] Rank objects' + summary: "[Beta] Rank objects" operationId: createRanking - description: | + description: > > ⚠️ **Beta Access Required** + > Contact your sales representative to gain access to this endpoint and start using it. - Use the `/ranking` endpoint to re-rank objects to show on a page. This endpoint can retrieve sponsored - and non-sonsored objects and rank them together, according to an appropriate context and behavior information. + + Use the `/ranking` endpoint to re-rank objects to show on a page. This endpoint can retrieve + sponsored + + and non-sonsored objects and rank them together, according to an appropriate context and + behavior information. requestBody: - description: | + description: > The context information to get the ranking, to rank organic and sponsored products. - - x-beta: 'true' + x-beta: "true" content: application/json: schema: @@ -484,27 +411,31 @@ paths: ranking: type: array items: - $ref: '#/components/schemas/RankingRequest' + $ref: "#/components/schemas/RankingRequest" minItems: 1 maxItems: 5 required: - ranking - example: - ranking: - - type: listings - slots: 3 - pageSize: 3 - category: - ids: ['sneakers', 'shoes'] - products: - ids: ['p_PJbnN', 'p_ojng4'] + examples: + - ranking: + - type: listings + slots: 3 + pageSize: 3 + category: + ids: + - sneakers + - shoes + products: + ids: + - p_PJbnN + - p_ojng4 required: true responses: - 201: + "201": description: > - The ranking results. - The list of winners will contain at most `slots` entries per auction. - It may contain fewer or no entries at all if there aren't enough products to fill the slots. + The ranking results. The list of winners will contain at most `slots` entries per + auction. It may contain fewer or no entries at all if there aren't enough products to + fill the slots. content: application/json: schema: @@ -513,140 +444,113 @@ paths: results: type: array items: - $ref: '#/components/schemas/RankingResult' + $ref: "#/components/schemas/RankingResult" minItems: 1 maxItems: 5 required: - results - example: - results: - - products: - - rank: 1 - type: organic - id: p_Mfk11 - resolvedItemId: WyJiX01mazExIiwiMTJhNTU4MjgtOGVhZC00Mjk5LTMyNjYtY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0== - - rank: 2 - type: sponsored - id: p_Mfk15 - resolvedItemId: WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0= - - rank: 3 - type: organic - id: p_PJbnN - resolvedItemId: WyJlX1BKYm5OIiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0= - error: false - 400: - $ref: '#/components/responses/BadRequest' - 401: - $ref: '#/components/responses/UnauthorizedError' - + examples: + - results: + - products: + - rank: 1 + type: organic + id: p_Mfk11 + resolvedItemId: WyJiX01mazExIiwiMTJhNTU4MjgtOGVhZC00Mjk5LTMyNjYtY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0== + - rank: 2 + type: sponsored + id: p_Mfk15 + resolvedItemId: WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0= + - rank: 3 + type: organic + id: p_PJbnN + resolvedItemId: WyJlX1BKYm5OIiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0= + error: false + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/UnauthorizedError" /toptimize/v1/predictions: post: tags: - Toptimize - summary: '[Beta] Add Quality Score' - description: | - Use the `/predictions` endpoint to get contextual predictions of conversion and relevance metrics, - which are personalized by user and context. - - In order to provide predictions, Topsort requires that events are also sent, as a source of - information. + summary: "[Beta] Add Quality Score" + description: > + Use the `/predictions` endpoint to get contextual predictions of conversion and relevance + metrics, which are personalized by user and context.In order to provide predictions, Topsort + requires that events are also sent, as a source of information. operationId: getPredictions requestBody: - description: | + description: > > ⚠️ **Beta Access Required** > Contact your sales representative to gain access to this endpoint and start using it. The context information for the predictions, including which metrics to predict. - x-beta: 'true' + x-beta: "true" content: application/json: schema: - $ref: '#/components/schemas/PredictionRequest' - example: - metrics: - ctr: true - opaqueUserId: 'u_9ske45' - productIds: ['p_PJbnN', 'p_ojng4'] - objectType: 'listings' + $ref: "#/components/schemas/PredictionRequest" required: true responses: - 200: + "200": description: > - The prediction results. This will provide a numerical value for each combination of metric/product - requested on the API call. + The prediction results. This will provide a numerical value for each combination of + metric/product requested on the API call. content: application/json: schema: - $ref: '#/components/schemas/PredictionResult' - example: - objectType: 'listings' - predictions: - - productId: 'p_PJbnN' - ctr: 0.03 - - productId: 'p_ojng4' - ctr: 0.056 - error: false - 400: - $ref: '#/components/responses/BadRequest' - 401: - $ref: '#/components/responses/UnauthorizedError' - + $ref: "#/components/schemas/PredictionResult" + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/UnauthorizedError" /toptimize/v1/retrieval: post: tags: - Toptimize - summary: '[Beta] Retrieve objects' - description: | + summary: "[Beta] Retrieve objects" + description: > > ⚠️ **Beta Access Required** + > Contact your sales representative to gain access to this endpoint and start using it. + Use the `/retrieval` endpoint to get recommendations of which products are relevant given a - certain context. Context is provided by user information, plus seed products. This can be used - to retrieve object to display on a PDP (single seed product) or in a cart (multiple seed products). + + certain context. Context is provided by user information, plus seed products. This can be + used + + to retrieve object to display on a PDP (single seed product) or in a cart (multiple seed + products). + In order to provide retrieval, Topsort requires that events are also sent, as a source of + information. operationId: retrieveObjects requestBody: - description: | + description: > The context information for the predictions, including which metrics to predict. - x-beta: 'true' + x-beta: "true" content: application/json: schema: - $ref: '#/components/schemas/RetrievalRequest' - example: - slots: 5 - opaqueUserId: 'u_9ske45' - seedProductIds: ['p_PJbnN', 'p_ojng4'] - mode: all - deviceType: mobile + $ref: "#/components/schemas/RetrievalRequest" required: true responses: - 200: + "200": description: > The retrieval results. Each retrieved products is accompanied by their relevancy score. content: application/json: schema: - $ref: '#/components/schemas/RetrievalResults' - example: - objectType: 'listing' - objects: - - id: 'p_xh90s' - value: 0.978 - - id: 'p_12lp0' - value: 0.953 - - id: 'p_ds7ui' - value: 0.877 - error: false - 400: - $ref: '#/components/responses/BadRequest' - 401: - $ref: '#/components/responses/UnauthorizedError' - + $ref: "#/components/schemas/RetrievalResults" + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/UnauthorizedError" components: responses: UnauthorizedError: @@ -656,12 +560,11 @@ components: content: application/json: schema: - $ref: '#/components/schemas/Error' - + $ref: "#/components/schemas/Error" schemas: - Category: + AuctionCategory: oneOf: - - $ref: '#/components/schemas/SingleCategory' + - $ref: "#/components/schemas/SingleCategory" - type: object title: Multiple Categories description: A set of categories for the purpose of running an auction. @@ -670,15 +573,18 @@ components: properties: ids: type: array - description: | - An array containing the category IDs of the bids that will participate in an auction. - In order to participate in an auction, a bid product must belong to **all** of the categories provided in the auction request. + description: > + An array containing the category IDs of the bids that will participate in an + auction. + + In order to participate in an auction, a bid product must belong to **all** of the + categories provided in the auction request. items: type: string description: A category ID. minLength: 1 minItems: 1 - example: + examples: - c_men_clothing - c_shoes - type: object @@ -689,18 +595,19 @@ components: properties: disjunctions: type: array - description: | + description: > An array of disjunctions. - In order to participate in an auction, a bid product must belong to at least one of the categories of the disjunction provided in the auction request. + + In order to participate in an auction, a bid product must belong to at least one of + the categories of the disjunction provided in the auction request. items: - $ref: '#/components/schemas/CategoryDisjunction' + $ref: "#/components/schemas/CategoryDisjunction" minItems: 1 maxItems: 5 - example: - - - c_red - - c_blue - + examples: + - c_red + - c_blue SingleCategory: type: object description: A category for the purpose of running an auction. @@ -711,20 +618,21 @@ components: type: string description: The category ID of the bids that will participate in an auction. minLength: 1 - example: c_yogurt - + examples: + - c_yogurt CategoryDisjunction: type: array - description: | + description: > An array of category IDs, describing a category disjunction. - A bid entity must belong to at least one of the categories in the disjunction in order to participate in the auction. + + A bid entity must belong to at least one of the categories in the disjunction in order to + participate in the auction. items: type: string description: A category ID. minimum: 1 minItems: 1 - Device: type: string description: The device for which the ads are meant for. @@ -732,15 +640,14 @@ components: - desktop - mobile default: desktop - DeviceType: type: string description: The device the user is on. enum: - desktop - mobile - example: mobile - + examples: + - mobile Page: type: object title: Page @@ -758,40 +665,52 @@ components: - cart - other description: Type of page. - example: 'category' + examples: + - category value: oneOf: - type: string description: Detail of the page, depending on the type - example: 'electronics' + examples: + - electronics - type: array items: type: string description: Only valid for type cart. Items on the cart - example: '[ "coffee", "cookies", "apples" ]' + examples: + - coffee + - cookies + - apples minItems: 1 pageId: type: string description: Identifies the page - example: '/category/electronics' - + examples: + - /category/electronics + occurredAt: + type: string + format: date-time + description: A RFC3339 formatted timestamp including UTC offset. + examples: + - 2009-01-01T12:59:59-05:00 OpaqueUserID: type: string description: - The opaque user ID is an anonymized unique identifier that maps to the original user ID without revealing the - original value. This identifier allows Topsort to correlate user activity between auctions and user - interactions, independent of the user's logged-in status. For apps or sites where users might interact while - logged out, we recommend generating a random identifier (UUIDv7) on the first load, storing it on local storage - (cookie, local storage, etc), and letting it live for at least a year. Otherwise, if your users are always - logged in for interactions, you may use a hash of your customer ID. Correct purchase attribution requires - long-lived opaque user IDs consistent between auction and event requests. - example: 71303ce0-de89-496d-8270-6434589615e8 - + The opaque user ID is an anonymized unique identifier that maps to the original user ID + without revealing the original value. This identifier allows Topsort to correlate user + activity between auctions and user interactions, independent of the user's logged-in status. + For apps or sites where users might interact while logged out, we recommend generating a + random identifier (UUIDv7) on the first load, storing it on local storage (cookie, local + storage, etc), and letting it live for at least a year. Otherwise, if your users are always + logged in for interactions, you may use a hash of your customer ID. Correct purchase + attribution requires long-lived opaque user IDs consistent between auction and event + requests. + examples: + - 71303ce0-de89-496d-8270-6434589615e8 PlacementId: type: integer format: int32 description: The marketplace's ID of the placement where the ad will appear. - GeoTargeting: type: object description: An object describing geographical information associated with this auction. @@ -801,7 +720,11 @@ components: location: description: The location this auction is being run for. type: string - + ResolvedBidID: + type: string + description: An opaque Topsort ID to be used when this item is interacted with. + examples: + - WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0= SponsoredListingsAuction: type: object description: | @@ -822,39 +745,35 @@ components: minimum: 1 description: Specifies the maximum number of auction winners that should be returned. category: - $ref: '#/components/schemas/Category' + $ref: "#/components/schemas/AuctionCategory" searchQuery: type: string description: The search string provided by a user. products: - $ref: '#/components/schemas/Products' + $ref: "#/components/schemas/Products" geoTargeting: - $ref: '#/components/schemas/GeoTargeting' + $ref: "#/components/schemas/GeoTargeting" opaqueUserId: - $ref: '#/components/schemas/OpaqueUserID' + $ref: "#/components/schemas/OpaqueUserID" placementId: - $ref: '#/components/schemas/PlacementId' + $ref: "#/components/schemas/PlacementId" required: - type - slots - example: - type: listings - slots: 2 - products: - ids: - - p_PJbnN - - p_ojng4 - - p_8VKDt - - p_Mfk15 - # category: - # id: c_yogurt - # searchQuery: Noosa Peach - geoTargeting: - location: New York - + examples: + - type: listings + slots: 2 + products: + ids: + - p_PJbnN + - p_ojng4 + - p_8VKDt + - p_Mfk15 + geoTargeting: + location: New York BannersAuction: type: object - description: | + description: > Describes the intent of running a banner ads auction. * For **Landing Page** banners, `category` and `searchQuery` must be empty. @@ -872,41 +791,39 @@ components: minimum: 1 description: Specifies the maximum number of auction winners that should be returned. category: - $ref: '#/components/schemas/Category' + $ref: "#/components/schemas/AuctionCategory" searchQuery: type: string description: The search string provided by a user. device: - $ref: '#/components/schemas/Device' + $ref: "#/components/schemas/Device" geoTargeting: - $ref: '#/components/schemas/GeoTargeting' + $ref: "#/components/schemas/GeoTargeting" slotId: type: string description: The ID of the banner placement for which this auction will be run for. minLength: 1 products: - $ref: '#/components/schemas/Products' + $ref: "#/components/schemas/Products" opaqueUserId: - $ref: '#/components/schemas/OpaqueUserID' + $ref: "#/components/schemas/OpaqueUserID" placementId: - $ref: '#/components/schemas/PlacementId' + $ref: "#/components/schemas/PlacementId" required: - type - slots - slotId - example: - type: banners - slots: 1 - slotId: categories-ribbon-banner - category: - id: c_yogurt - + examples: + - type: banners + slots: 1 + slotId: categories-ribbon-banner + category: + id: c_yogurt AuctionRequest: description: Describes the intent of running a single auction. oneOf: - - $ref: '#/components/schemas/SponsoredListingsAuction' - - $ref: '#/components/schemas/BannersAuction' - + - $ref: "#/components/schemas/SponsoredListingsAuction" + - $ref: "#/components/schemas/BannersAuction" RankingRequest: type: object description: | @@ -926,43 +843,38 @@ components: type: integer format: int32 minimum: 1 - description: Specifies the maximum number of ranked objects per page that should be returned. + description: + Specifies the maximum number of ranked objects per page that should be returned. page: - $ref: '#/components/schemas/Page' + $ref: "#/components/schemas/Page" category: - $ref: '#/components/schemas/Category' + $ref: "#/components/schemas/AuctionCategory" device: - $ref: '#/components/schemas/Device' + $ref: "#/components/schemas/Device" geoTargeting: - $ref: '#/components/schemas/GeoTargeting' + $ref: "#/components/schemas/GeoTargeting" products: - $ref: '#/components/schemas/Products' + $ref: "#/components/schemas/Products" opaqueUserId: - type: string - description: | - The opaque user ID allows correlating user activity, such as Impressions, Clicks and Purchases, - whether or not they are actually logged in. It must be long lived (at least a year) so that Topsort can attribute purchases. - If your users are always logged in you may use a hash of your customer ID. - If your users may interact with your app or site while logged out we - recommend generating a random identifier (UUIDv4) on first load and store it on - local storage (cookie, local storage, etc) and let it live for at least a year. - minLength: 1 - example: 71303ce0-de89-496d-8270-6434589615e8 + $ref: "#/components/schemas/OpaqueUserID" required: - type - slots - pageSize - page - opaqueUserId - example: - type: listings - slots: 10 - pageSize: 10 - category: - ids: ['sneakers', 'shoes'] - products: - ids: ['p_PJbnN', 'p_ojng4'] - + examples: + - type: listings + slots: 10 + pageSize: 10 + category: + ids: + - sneakers + - shoes + products: + ids: + - p_PJbnN + - p_ojng4 PredictionRequest: type: object properties: @@ -977,14 +889,9 @@ components: type: boolean description: If `true` a Conversion Rate prediction will be made. opaqueUserId: - type: string - description: - The opaque user ID is an anonymized unique identifier that maps to the original user ID without revealing the - original value. This identifier allows Topsort to use interactions information to later on provide a prediction - of the outcome of the interaction between the user and a product. - example: 71303ce0-de89-496d-8270-6434589615e8 + $ref: "#/components/schemas/OpaqueUserID" page: - $ref: '#/components/schemas/Page' + $ref: "#/components/schemas/Page" objectType: type: string description: The type of object that is being reported on the interaction. @@ -992,36 +899,43 @@ components: - listings - banners deviceType: - $ref: '#/components/schemas/DeviceType' + $ref: "#/components/schemas/DeviceType" productIds: type: array items: type: string - example: ['p_1234', 'p_5678'] + examples: + - p_1234 + - p_5678 + examples: + - metrics: + ctr: true + opaqueUserId: u_9ske45 + productIds: + - p_PJbnN + - p_ojng4 + objectType: + - listings required: - metrics - productIds - objectType - opaqueUserId - RetrievalRequest: type: object properties: slots: type: integer description: How many objects to retrieve. - example: 10 + examples: + - 10 + - 50 minimum: 1 maximum: 100 opaqueUserId: - type: string - description: - The opaque user ID is an anonymized unique identifier that maps to the original user ID without revealing the - original value. This identifier allows Topsort to use interactions information to later on provide a prediction - of the outcome of the interaction between the user and a product. - example: 71303ce0-de89-496d-8270-6434589615e8 + $ref: "#/components/schemas/OpaqueUserID" page: - $ref: '#/components/schemas/Page' + $ref: "#/components/schemas/Page" objectType: type: string description: The type of object that needs to be retrieved. @@ -1029,12 +943,14 @@ components: - listings - banners deviceType: - $ref: '#/components/schemas/DeviceType' + $ref: "#/components/schemas/DeviceType" seedProductIds: type: array items: type: string - example: ['p_1234', 'p_5678'] + examples: + - p_1234 + - p_5678 mode: type: string description: Retrieval mode, how to interpret the context to get objects. @@ -1043,27 +959,33 @@ components: - complement - similar default: all + examples: + - slots: 5 + opaqueUserId: u_9ske45 + seedProductIds: + - p_PJbnN + - p_ojng4 + mode: all + deviceType: + - mobile required: - slots - seedProductIds - opaqueUserId - objectType - AuctionResult: discriminator: propertyName: resultType mapping: - listings: '#/components/schemas/SponsoredListingsAuctionResult' - banners: '#/components/schemas/BannersAuctionResult' + listings: "#/components/schemas/SponsoredListingsAuctionResult" + banners: "#/components/schemas/BannersAuctionResult" oneOf: - - $ref: '#/components/schemas/SponsoredListingsAuctionResult' - - $ref: '#/components/schemas/BannersAuctionResult' - + - $ref: "#/components/schemas/SponsoredListingsAuctionResult" + - $ref: "#/components/schemas/BannersAuctionResult" TravelAuctionResult: oneOf: - - $ref: '#/components/schemas/HotelsAuctionResult' - - $ref: '#/components/schemas/FlightsAuctionResult' - + - $ref: "#/components/schemas/HotelsAuctionResult" + - $ref: "#/components/schemas/FlightsAuctionResult" BannersAuctionResult: type: object properties: @@ -1072,19 +994,19 @@ components: winners: type: array items: - $ref: '#/components/schemas/BannersWinner' + $ref: "#/components/schemas/BannersWinner" description: > - Array of winner objects in order from highest to lowest bid. - It will be empty if there were no qualifying bids or if there was an error. + Array of winner objects in order from highest to lowest bid. 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 + examples: + - false required: - winners - error - resultType - SponsoredListingsAuctionResult: type: object properties: @@ -1093,19 +1015,19 @@ components: winners: type: array items: - $ref: '#/components/schemas/SponsoredListingsWinner' + $ref: "#/components/schemas/SponsoredListingsWinner" description: > - Array of winner objects in order from highest to lowest bid. - It will be empty if there were no qualifying bids or if there was an error. + Array of winner objects in order from highest to lowest bid. 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 + examples: + - false required: - winners - error - resultType - SponsoredListingsWinner: type: object required: @@ -1119,9 +1041,9 @@ components: type: integer format: int32 description: > - Where the product's bid ranked in the auction. - One-based, so the product with rank 1 won the auction. - In an auction response, the winners array is sorted so rank will match the entry's index. + Where the product's bid ranked in the auction. One-based, so the product with rank 1 won + the auction. In an auction response, the winners array is sorted so rank will match the + entry's index. minimum: 1 type: type: string @@ -1133,18 +1055,17 @@ components: - url id: type: string - description: |- + description: The marketplace's ID of the winning entity, depending on the target of the campaign. - example: p_Mfk15 + examples: + - p_Mfk15 resolvedBidId: - type: string - description: An opaque Topsort ID to be used when this item is interacted with. - example: WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0= + $ref: "#/components/schemas/ResolvedBidID" campaignId: type: string description: The ID of the campaign that won the auction. - example: 4bcc6093-f367-4df2-aa1b-7c1674dd6441 - + examples: + - 4bcc6093-f367-4df2-aa1b-7c1674dd6441 BannersWinner: type: object required: @@ -1158,9 +1079,9 @@ components: type: integer format: int32 description: > - Where the product's bid ranked in the auction. - One-based, so the product with rank 1 won the auction. - In an auction response, the winners array is sorted so rank will match the entry's index. + Where the product's bid ranked in the auction. One-based, so the product with rank 1 won + the auction. In an auction response, the winners array is sorted so rank will match the + entry's index. minimum: 1 type: type: string @@ -1172,27 +1093,25 @@ components: - url id: type: string - description: |- + description: The marketplace's ID of the winning entity, depending on the target of the campaign. - example: p_Mfk15 + examples: + - p_Mfk15 resolvedBidId: - type: string - description: An opaque Topsort ID to be used when this item is interacted with. - example: WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0= + $ref: "#/components/schemas/ResolvedBidID" campaignId: type: string description: The ID of the campaign that won the auction. - example: 4bcc6093-f367-4df2-aa1b-7c1674dd6441 + examples: + - 4bcc6093-f367-4df2-aa1b-7c1674dd6441 asset: description: The list of available sources for a banner. type: array items: - $ref: '#/components/schemas/AssetSource' + $ref: "#/components/schemas/AssetSource" minItems: 1 - HotelsAuctionResult: - $ref: '#/components/schemas/SponsoredListingsAuctionResult' - + $ref: "#/components/schemas/SponsoredListingsAuctionResult" FlightsAuctionResult: type: object properties: @@ -1201,19 +1120,19 @@ components: winners: type: array items: - $ref: '#/components/schemas/FlightsWinner' + $ref: "#/components/schemas/FlightsWinner" description: > - Array of winner objects in order from highest to lowest bid. - It will be empty if there were no qualifying bids or if there was an error. + Array of winner objects in order from highest to lowest bid. 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 + examples: + - false required: - winners - error - resultType - FlightsWinner: type: object required: @@ -1228,9 +1147,9 @@ components: type: integer format: int32 description: > - Where the product's bid ranked in the auction. - One-based, so the product with rank 1 won the auction. - In an auction response, the winners array is sorted so rank will match the entry's index. + Where the product's bid ranked in the auction. One-based, so the product with rank 1 won + the auction. In an auction response, the winners array is sorted so rank will match the + entry's index. minimum: 1 type: type: string @@ -1239,21 +1158,21 @@ components: - product id: type: string - description: |- - The marketplace's ID of the winning flight product, depending on the target of the campaign. - example: p_Mfk15 + description: + The marketplace's ID of the winning flight product, depending on the target of the + campaign. + examples: + - p_Mfk15 resolvedBidId: - type: string - description: An opaque Topsort ID to be used when this item is interacted with. - example: WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0= + $ref: "#/components/schemas/ResolvedBidID" campaignId: type: string description: The ID of the campaign that won the auction. - example: 4bcc6093-f367-4df2-aa1b-7c1674dd6441 + examples: + - 4bcc6093-f367-4df2-aa1b-7c1674dd6441 variationID: type: string description: The marketplace's ID for the winning flight product's variation. - RankingResult: type: object properties: @@ -1262,18 +1181,18 @@ components: results: type: array items: - $ref: '#/components/schemas/RankingWinner' - description: > + $ref: "#/components/schemas/RankingWinner" + description: | Array of ranking objects in order from highest to lowest relevancy. error: type: boolean description: A boolean indicating whether this auction was resolved successfully. - example: false + examples: + - false required: - results - error - resultType - RankingWinner: type: object required: @@ -1285,7 +1204,7 @@ components: rank: type: integer format: int32 - description: > + description: | Where is the product ranked in the auction. minimum: 1 type: @@ -1296,14 +1215,14 @@ components: - sponsored id: type: string - description: |- - The marketplace's ID of the ranked entity. - example: p_Mfk15 + description: The marketplace's ID of the ranked entity. + examples: + - p_Mfk15 resolvedItemId: type: string description: An opaque Topsort ID to be used when this item is interacted with. - example: WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0= - + examples: + - WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0= PredictionResult: type: object properties: @@ -1312,6 +1231,8 @@ components: enum: - listings - banners + examples: + - listings description: The type of object that was predicted. predictions: type: array @@ -1327,12 +1248,23 @@ components: cvr: type: number description: Conversion Rate prediction. - description: > - Predicted objects. + description: Predicted objects + examples: + - productId: product-123 + ctr: 0.05 + cvr: 0.101 + examples: + - objectType: listings + predictions: + - productId: p_PJbnN + ctr: 0.03 + cvr: 0.06 + - productId: p_ojng4 + ctr: 0.056 + cvr: 0.091 required: - objectType - predictions - RetrievalResults: type: object properties: @@ -1353,12 +1285,20 @@ components: score: type: number description: Relevance score for the retrieved products. - description: > - Retrieved objects. + description: Retrieved objects. + examples: + - objectType: listing + objects: + - id: p_xh90s + value: 0.978 + - id: p_12lp0 + value: 0.953 + - id: p_ds7ui + value: 0.877 + error: false required: - objectType - objects - InteractionObject: type: object description: Information regarding an organic or non-sponsored event. @@ -1374,60 +1314,28 @@ components: assetId: type: string description: When type is `banner`, signals the ID of the asset of the banner - example: banner_asset_001 + examples: + - banner_asset_001 clickType: type: string - description: When type is `listing`, signals the specific interaction flavor with the listing. + description: + When type is `listing`, signals the specific interaction flavor with the listing. enum: - product - like - add-to-cart - - # Dimensions: - # type: object - # description: The dimensions of this source. - # properties: - # width: - # type: integer - # format: int32 - # description: The source width in pixels. - # minimum: 1 - # height: - # type: integer - # format: int32 - # description: The source height in pixels. - # minimum: 1 - # required: - # - width - # - height - AssetSource: description: A source available for an asset (banner or video). type: object properties: - # mimeType: - # type: string - # description: The MIME type of this source. - # example: image/png - # dimensions: - # $ref: '#/components/schemas/Dimensions' - # fileSize: - # type: integer - # format: int32 - # description: The file size in bytes. - # example: 238490 url: type: string format: uri description: > - A vendor provided asset that the marketplace has to use as a banner. - The asset will be served by Topsort's CDN. + A vendor provided asset that the marketplace has to use as a banner. The asset will be + served by Topsort's CDN. required: - # - mimeType - # - dimensions - # - fileSize - url - Products: required: - ids @@ -1436,35 +1344,41 @@ components: ids: type: array description: > - An array of product IDs that should participate in the auction. - We recommend sending no more than 500 products per auction. + An array of product IDs that should participate in the auction. We recommend sending no + more than 500 products per auction. items: type: string description: > - The marketplace's ID of a product which will participate in the auction. - These ID must match those in the catalog integration with Topsort. - example: p_SA0238 + The marketplace's ID of a product which will participate in the auction. These ID must + match those in the catalog integration with Topsort. + examples: + - p_SA0238 minLength: 1 minItems: 1 maxItems: 10000 qualityScores: type: array - description: | - An array of marketplace defined quality scores, each corresponding to the product ID with matching array index. - If given, these values will be combined with our internal quality scores to provide a score + description: > + An array of marketplace defined quality scores, each corresponding to the product ID + with matching array index. + + If given, these values will be combined with our internal quality scores to provide a + score + that better represents the relevance of the participating products. + Note that the length of this array must be the same as the length of the `ids` array and + that the values must be between 0 and 1. items: type: number - minimum: 0 maximum: 1 - exclusiveMinimum: true - example: 0.75 + exclusiveMinimum: 0 + examples: + - 0.75 format: double minItems: 1 maxItems: 10000 - SponsoredBrandAuctionRequest: type: object description: | @@ -1493,11 +1407,11 @@ components: id: ne5n2vzri6o92 properties: category: - $ref: '#/components/schemas/SingleCategory' + $ref: "#/components/schemas/SingleCategory" products: - $ref: '#/components/schemas/Products' + $ref: "#/components/schemas/Products" opaqueUserId: - $ref: '#/components/schemas/OpaqueUserID' + $ref: "#/components/schemas/OpaqueUserID" x-examples: Example 1: auctions: @@ -1506,22 +1420,23 @@ components: triggers: products: ids: - - '1' - - '8' - + - "1" + - "8" SponsoredBrandAuctionResult: type: object properties: winners: type: array items: - $ref: '#/components/schemas/SponsoredBrandWinner' - description: | - Array of winner objects in order from highest to lowest bid. It will be empty if there were no qualifying bids or if there was an error. + $ref: "#/components/schemas/SponsoredBrandWinner" + description: > + Array of winner objects in order from highest to lowest bid. 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 + examples: + - false required: - winners - error @@ -1531,16 +1446,16 @@ components: - winners: - rank: 1 resolvedBidId: ChAGc-G66Wt7LKQEOcW8VBdIEhABjz_zDXx7db-ZYpxiwJ3DGhABjr4Lt_J0_a7Xv_uIfyOXIgUKATEQATDrrg8 - productId: '1' + productId: "1" title: Brand Example Promo 1 assets: - - url: 'https://assets.hosted.topsort.com/5bcccb92e5eaaa73ce9fcc545e944865bf70e9b60e5a048979769282450343c4/example-banner-1.png' + - url: https://assets.hosted.topsort.com/5bcccb92e5eaaa73ce9fcc545e944865bf70e9b60e5a048979769282450343c4/example-banner-1.png role: image contentType: image/png contentLength: 33902 width: 920 height: 920 - - url: 'https://assets.hosted.topsort.com/c27c9cd94badc90fb50827e144dfacb2f51a601560905b950f525cec725ea85f/example-logo-1.png' + - url: https://assets.hosted.topsort.com/c27c9cd94badc90fb50827e144dfacb2f51a601560905b950f525cec725ea85f/example-logo-1.png role: logo contentType: image/png contentLength: 80648 @@ -1549,16 +1464,16 @@ components: campaignId: 018f3ff3-0d7c-7b75-bf99-629c62c09dc3 - rank: 2 resolvedBidId: ChAGc-G66Wt7LKQEOcW8VBdIEhABk0pue7N5wYmzE04uO_iOGhABjr4Lt_J0_a7Xv_uIfyOXIgUKATgQATDrrg8 - productId: '8' + productId: "8" title: Brand Example Promo 2 assets: - - url: 'https://assets.hosted.topsort.com/c049a46d834ab071cdde63e401d4efcd554e1a124f05c4ba9b3743fed2d43c4b/example-banner-2.jpeg' + - url: https://assets.hosted.topsort.com/c049a46d834ab071cdde63e401d4efcd554e1a124f05c4ba9b3743fed2d43c4b/example-banner-2.jpeg role: image contentType: image/jpeg contentLength: 4505 width: 403 height: 125 - - url: 'https://assets.hosted.topsort.com/db41a8b8b22c5ed9091f9f154b552b6bc1d1dbeb85059190f1c3b202977938f1/example-logo-2.png' + - url: https://assets.hosted.topsort.com/db41a8b8b22c5ed9091f9f154b552b6bc1d1dbeb85059190f1c3b202977938f1/example-logo-2.png role: logo contentType: image/png contentLength: 34747 @@ -1566,7 +1481,6 @@ components: height: 160 campaignId: 01934a6e-7bb3-79c1-89b3-134e2e3bf88e error: false - SponsoredBrandWinner: type: object required: @@ -1579,33 +1493,33 @@ components: type: integer format: int32 description: > - Where the product's bid ranked in the auction. - One-based, so the product with rank 1 won the auction. - In an auction response, the winners array is sorted so rank will match the entry's index. + Where the product's bid ranked in the auction. One-based, so the product with rank 1 won + the auction. In an auction response, the winners array is sorted so rank will match the + entry's index. minimum: 1 productId: type: string - description: |- + description: The marketplace's ID of the winning entity, depending on the target of the campaign. - example: p_Mfk15 + examples: + - p_Mfk15 resolvedBidId: - type: string - description: An opaque Topsort ID to be used when this item is interacted with. - example: WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0= + $ref: "#/components/schemas/ResolvedBidID" title: type: string - description: An optional title for the sponsored brand selected when creating the campaign. + description: + An optional title for the sponsored brand selected when creating the campaign. vendorId: type: string description: The ID of the vendor associated with this sponsored brand winner. - example: v_8fj2D + examples: + - v_8fj2D assets: description: Assets used to render the sponsored brand ad. type: array items: - $ref: '#/components/schemas/SponsoredBrandAsset' + $ref: "#/components/schemas/SponsoredBrandAsset" minItems: 1 - SponsoredBrandAsset: type: object properties: @@ -1613,8 +1527,8 @@ components: type: string format: uri description: > - A vendor provided asset that the marketplace has to render. - The asset will be served by Topsort's CDN. + A vendor provided asset that the marketplace has to render. The asset will be served by + Topsort's CDN. role: type: string description: The role of the asset. It can be either `logo` or `image`. @@ -1633,13 +1547,11 @@ components: type: integer format: uint32 description: The asset height in pixels. - TravelAuctionRequest: description: Describes the intent of running a single auction. oneOf: - - $ref: '#/components/schemas/HotelsAuctionRequest' - - $ref: '#/components/schemas/FlightsAuctionRequest' - + - $ref: "#/components/schemas/HotelsAuctionRequest" + - $ref: "#/components/schemas/FlightsAuctionRequest" HotelsAuctionRequest: type: object description: Describes the intent of running a hotel travel auction. @@ -1655,14 +1567,16 @@ components: slots: type: integer format: int32 - description: Specifies the maximum number of auction winners that should be returned. If slots > 40, it is capped at 40. + description: + Specifies the maximum number of auction winners that should be returned. If slots > 40, + it is capped at 40. minimum: 1 maximum: 40 products: type: array description: An array of hotels products that should participate in the auction. items: - $ref: '#/components/schemas/HotelsTravelProduct' + $ref: "#/components/schemas/HotelsTravelProduct" category: description: A category for the purpose of running an auction. type: object @@ -1677,10 +1591,10 @@ components: type: string description: The category ID of the bids that will participate in an auction. minLength: 1 - example: c_buenos-aires-hotels + examples: + - c_buenos-aires-hotels travelContext: - $ref: '#/components/schemas/HotelsTravelContext' - + $ref: "#/components/schemas/HotelsTravelContext" HotelsTravelProduct: type: object required: @@ -1689,20 +1603,20 @@ components: id: type: string description: ID to identify hotel product. - example: miami-hotel + examples: + - miami-hotel qualityScore: type: number - minimum: 0 maximum: 1 - exclusiveMinimum: true - example: 0.75 + exclusiveMinimum: 0 + examples: + - 0.75 format: double description: | If given, this value will be combined with our internal quality score to provide a score that better represents the relevance of the participating products. If not given it will default to 1. Values must be between 0 and 1. - BaseTravelContext: type: object required: @@ -1713,22 +1627,27 @@ components: minLength: 1 maxLength: 64 description: Web site requesting the auction - example: argentina + examples: + - argentina passengers: type: integer description: Number of passengers. Must not exceed 10. - example: 3 + examples: + - 3 travelStartDate: type: string format: date description: RFC3339 formatted date representing the travel start point. - example: '2009-01-01' + examples: + - 2024-06-10 travelEndDate: type: string format: date - description: | - RFC3339 formatted date representing the travel end point. Must be greater than start date. - example: '2009-01-15' + description: > + RFC3339 formatted date representing the travel end point. Must be greater than start + date. + examples: + - 2025-08-10 travelerType: type: string enum: @@ -1742,11 +1661,9 @@ components: platform: type: string description: Platform e.g. "app", "mobile", "web", ... - HotelsTravelContext: allOf: - - $ref: '#/components/schemas/BaseTravelContext' - + - $ref: "#/components/schemas/BaseTravelContext" FlightsAuctionRequest: type: object description: Describes the intent of running a flight travel auction. @@ -1762,17 +1679,18 @@ components: slots: type: integer format: int32 - description: Specifies the maximum number of auction winners that should be returned. If slots > 40, it is capped at 40. + description: + Specifies the maximum number of auction winners that should be returned. If slots > 40, + it is capped at 40. minimum: 1 maximum: 40 products: type: array description: An array of flight products that should participate in the auction. items: - $ref: '#/components/schemas/FlightsTravelProduct' + $ref: "#/components/schemas/FlightsTravelProduct" travelContext: - $ref: '#/components/schemas/FlightsTravelContext' - + $ref: "#/components/schemas/FlightsTravelContext" FlightsTravelProduct: type: object required: @@ -1781,7 +1699,8 @@ components: id: type: string description: ID to identify flight product. - example: L0_SAO-ORL + examples: + - L0_SAO-ORL variationID: type: string description: ID to identify flight product variation. @@ -1790,20 +1709,19 @@ components: description: Flight product variation total price in marketplace currency. qualityScore: type: number - minimum: 0 maximum: 1 - exclusiveMinimum: true - example: 0.75 + exclusiveMinimum: 0 + examples: + - 0.75 format: double description: | If given, this value will be combined with our internal quality score to provide a score that better represents the relevance of the participating products. If not given it will default to 1. Values must be between 0 and 1. - FlightsTravelContext: allOf: - - $ref: '#/components/schemas/BaseTravelContext' + - $ref: "#/components/schemas/BaseTravelContext" - type: object properties: route: @@ -1812,7 +1730,6 @@ components: flightType: type: string description: Flight type e.g. "round_trip", "one_way", ... - Error: type: object required: @@ -1846,16 +1763,23 @@ components: - too_few_impressions - too_few_slots - too_many_auctions + examples: + - bad_request + - no_products docUrl: type: string format: uri description: A link to a documentation page providing more information about the error. - example: https://docs.topsort.com/reference/errors + examples: + - https://api.docs.topsort.com/reference/errors message: type: string description: > - Human-readable explanation of or details about the error. - The string for a given error may change over time; code should not parse or dispatch based on particular values for this field. + Human-readable explanation of or details about the error. The string for a given error + may change over time; code should not parse or dispatch based on particular values for + this field. + examples: + - could not find the provided resolved bid id Placement: type: object required: @@ -1864,21 +1788,19 @@ components: properties: path: type: string - description: | - URL path of the page triggering the event. - - For web apps, this can be obtained in JS using `window.location.pathname`. - - For mobile apps, use the deep link for the current view, if available. - Otherwise, encode the view from which the event occurred in your app as a path-like string (e.g. `/root/categories/:categoryId`). + description: > + URL path of the page triggering the event. For web apps, this can be obtained in JS + using `window.location.pathname`. For mobile apps, use the deep link for the current + view, if available. Otherwise, encode the view from which the event occurred in your app + as a path-like string (e.g. `/root/categories/:categoryId`). minLength: 1 - example: /categories/dairy + examples: + - /categories/dairy position: type: integer description: > - For components with multiple items - (i.e. search results, similar products, etc), - this should indicate the index of a given item within that list. + For components with multiple items (i.e. search results, similar products, etc), this + should indicate the index of a given item within that list. minimum: 1 page: type: integer @@ -1890,12 +1812,13 @@ components: description: > For paginated pages this should indicate how many items are in each result page. minimum: 1 - example: 15 + examples: + - 15 productId: type: string description: > - The ID of the product associated to the page in which this event occurred, if applicable. - This ID must match the ID provided through the catalog service. + The ID of the product associated to the page in which this event occurred, if + applicable. This ID must match the ID provided through the catalog service. minLength: 1 categoryIds: type: array @@ -1904,21 +1827,23 @@ components: minLength: 1 description: A category ID. description: > - An array of IDs of the categories associated to the page in which this event occurred, if applicable. - These IDs must match the IDs provided through the catalog service. + An array of IDs of the categories associated to the page in which this event occurred, + if applicable. These IDs must match the IDs provided through the catalog service. minItems: 1 searchQuery: type: string description: > - The search string provided by the user in the page where this event occurred, if applicable. - This search string must match the searchQuery field that was provided in the auction request (if provided). + The search string provided by the user in the page where this event occurred, if + applicable. This search string must match the searchQuery field that was provided in the + auction request (if provided). minLength: 1 - Entity: + EventEntity: type: object description: > - `Entity` is meant for reporting organic events, not sponsored or promoted products. It refers to the object - involved in the organic interaction. But, in most cases, you won't need to fill in this object. Be aware that - if `resolvedBidId` has any value, `entity` will be disregarded. + `Entity` is meant for reporting organic events, not sponsored or promoted products. It + refers to the object involved in the organic interaction. But, in most cases, you won't need + to fill in this object. Be aware that if `resolvedBidId` has any value, `entity` will be + disregarded. required: - id - type @@ -1941,95 +1866,97 @@ components: impressions: type: array items: - $ref: '#/components/schemas/Impression' + $ref: "#/components/schemas/Impression" minItems: 1 maxItems: 50 clicks: type: array items: - $ref: '#/components/schemas/Click' + $ref: "#/components/schemas/Click" minItems: 1 maxItems: 50 purchases: type: array items: - $ref: '#/components/schemas/Purchase' + $ref: "#/components/schemas/Purchase" minItems: 1 maxItems: 50 pageviews: type: array items: - $ref: '#/components/schemas/Pageview' + $ref: "#/components/schemas/Pageview" minItems: 1 maxItems: 50 minProperties: 1 - example: - impressions: - - id: eb874c98-bf4d-40a9-ae6d-fcf4cecb535c - occurredAt: '2019-01-01T12:59:59-05:00' - opaqueUserId: 71303ce0-de89-496d-8270-6434589615e8 - placement: - path: /categories/dairy - position: 1 - page: 1 - pageSize: 15 - categoryId: 9BLIe - resolvedBidId: WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0= - deviceType: mobile - channel: onsite - clicks: - - id: b39d39ed-ea0e-4059-9d15-4990b39c85a2 - occurredAt: '2019-01-01T13:01:42-05:00' - opaqueUserId: 71303ce0-de89-496d-8270-6434589615e8 - placement: - path: /categories/dairy - position: 1 - page: 1 - pageSize: 15 - categoryId: 9BLIe - resolvedBidId: WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0= - deviceType: mobile - channel: offsite - purchases: - - id: 0e06c899-b2cd-4e0d-b0de-8aefb4b6d0a0 - items: - - productId: p_SA0238 - unitPrice: 12.95 - quantity: 2 - vendorId: v_8fj2D - - productId: p_oajf2D - unitPrice: 1.49 - occurredAt: '2019-01-01T12:59:59-05:00' - opaqueUserId: 71303ce0-de89-496d-8270-6434589615e8 - deviceType: desktop - channel: onsite - - id: b7147656-504f-4ae7-b335-740829ff64c6 - items: - - productId: p_SA0279 - unitPrice: 119.95 - quantity: 5 - vendorId: v_8fj2D - occurredAt: '2019-01-01T13:59:59-05:00' - opaqueUserId: 71303ce0-de89-496d-8270-6434589615e8 - channel: instore - pageviews: - - id: 8f648a8e-830c-4bb4-9d93-6ea80075ca82 - occurredAt: '2019-01-01T12:59:58-05:00' - opaqueUserId: 71303ce0-de89-496d-8270-6434589615e8 - page: - type: category - pageId: /categories/dairy - value: dairy - deviceType: mobile - channel: onsite + examples: + - impressions: + - id: eb874c98-bf4d-40a9-ae6d-fcf4cecb535c + occurredAt: 2019-01-01T12:59:59-05:00 + opaqueUserId: 71303ce0-de89-496d-8270-6434589615e8 + placement: + path: /categories/dairy + position: 1 + page: 1 + pageSize: 15 + categoryId: 9BLIe + resolvedBidId: WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0= + deviceType: mobile + channel: onsite + - clicks: + - id: b39d39ed-ea0e-4059-9d15-4990b39c85a2 + occurredAt: 2019-01-01T13:01:42-05:00 + opaqueUserId: 71303ce0-de89-496d-8270-6434589615e8 + placement: + path: /categories/dairy + position: 1 + page: 1 + pageSize: 15 + categoryId: 9BLIe + resolvedBidId: WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0= + deviceType: mobile + channel: offsite + - purchases: + - id: 0e06c899-b2cd-4e0d-b0de-8aefb4b6d0a0 + items: + - productId: p_SA0238 + unitPrice: 12.95 + quantity: 2 + vendorId: v_8fj2D + - productId: p_oajf2D + unitPrice: 1.49 + occurredAt: 2019-01-01T12:59:59-05:00 + opaqueUserId: 71303ce0-de89-496d-8270-6434589615e8 + deviceType: desktop + channel: onsite + - id: b7147656-504f-4ae7-b335-740829ff64c6 + items: + - productId: p_SA0279 + unitPrice: 119.95 + quantity: 5 + vendorId: v_8fj2D + occurredAt: 2019-01-01T13:59:59-05:00 + opaqueUserId: 71303ce0-de89-496d-8270-6434589615e8 + channel: instore + - pageviews: + - id: 8f648a8e-830c-4bb4-9d93-6ea80075ca82 + occurredAt: 2019-01-01T12:59:58-05:00 + opaqueUserId: 71303ce0-de89-496d-8270-6434589615e8 + page: + type: category + pageId: /categories/dairy + value: dairy + deviceType: mobile + channel: onsite Impression: type: object description: > - An impression means a promotable has become visible to the consumer. - For promoted entities, include the `resolvedBidId` field from the `/v2/auctions` response. - For unpromoted entities, include the `entity` field to describe what was seen. - In case you cannot send an impression when the product becomes visible, send us an impression event when the product was rendered in the HTML or, if that's also not possible, when your API returns the results. - It is important to select the most specific event so that your vendors have more accurate CTR metrics, which will allow them to better predict their campaigns. + An impression means a promotable has become visible to the consumer. For promoted entities, + include the `resolvedBidId` field from the `/v2/auctions` response. For unpromoted entities, + include the `entity` field to describe what was seen. In case you cannot send an impression + when the product becomes visible, send us an impression event when the product was rendered + in the HTML or, if that's also not possible, when your API returns the results. It is + important to select the most specific event so that your vendors have more accurate CTR + metrics, which will allow them to better predict their campaigns. required: - occurredAt - opaqueUserId @@ -2037,56 +1964,55 @@ components: additionalProperties: false properties: resolvedBidId: - type: string - description: If the impression is over an ad promotion, this is the `resolvedBidId` field received from the `/auctions` request. In most situations, especially when reporting a sponsored interaction, you'll want to fill in this field. - example: WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0= + $ref: "#/components/schemas/ResolvedBidID" + description: > + If the impression is over an ad promotion, this is the `resolvedBidId` field received + from the `/auctions` request. In most situations, especially when reporting a sponsored + interaction, you'll want to fill in this field. entity: - $ref: '#/components/schemas/Entity' + $ref: "#/components/schemas/EventEntity" placement: - $ref: '#/components/schemas/Placement' + $ref: "#/components/schemas/Placement" occurredAt: - type: string - format: date-time - description: RFC3339 formatted timestamp including UTC offset. - example: '2009-01-01T12:59:59-05:00' + $ref: "#/components/schemas/occurredAt" opaqueUserId: - $ref: '#/components/schemas/OpaqueUserID' + $ref: "#/components/schemas/OpaqueUserID" id: - type: string - description: > - The marketplace's unique ID for the impression. - This field ensures the event reporting is idempotent in case there is a network issue and the request is retried. - If there is no impression model on the marketplace side, generate a unique string that does not change if the event is resent. - minLength: 1 - example: eb874c98-bf4d-40a9-ae6d-fcf4cecb535c + $ref: "#/components/schemas/EventIdentifier" additionalAttribution: - $ref: '#/components/schemas/Entity' + $ref: "#/components/schemas/EventEntity" page: - $ref: '#/components/schemas/Page' + $ref: "#/components/schemas/Page" object: - $ref: '#/components/schemas/InteractionObject' + $ref: "#/components/schemas/InteractionObject" externalCampaignId: type: string description: Marketplace provided ID for a campaign - example: 'awareness-campaign-2025' + examples: + - awareness-campaign-2025 externalVendorId: type: string description: Marketplace provided ID for a vendor - example: 'my-new-vendor' + examples: + - my-new-vendor deviceType: - $ref: '#/components/schemas/DeviceType' + $ref: "#/components/schemas/DeviceType" channel: type: string description: Optional. The channel where the event occurred. - enum: ['onsite', 'offsite', 'instore'] - example: 'onsite' - + enum: + - onsite + - offsite + - instore + examples: + - onsite Click: description: > - A click is sent to Topsort when the consumer has clicked on a promotable. - For promoted entities, include the `resolvedBidId` field from the `/v2/auctions` response. - For unpromoted entities, include the `entity` field to describe what was clicked. - Topsort charges the vendor and pays the marketplace for clicks on ads in promoted placements on the marketplace app. + A click is sent to Topsort when the consumer has clicked on a promotable. For promoted + entities, include the `resolvedBidId` field from the `/v2/auctions` response. For unpromoted + entities, include the `entity` field to describe what was clicked. Topsort charges the + vendor and pays the marketplace for clicks on ads in promoted placements on the marketplace + app. type: object required: - occurredAt @@ -2095,37 +2021,31 @@ components: additionalProperties: false properties: resolvedBidId: - type: string - description: If the click is over an ad promotion, this is the `resolvedBidId` field received from the `/auctions` request. In most situations, especially when reporting a sponsored interaction, you'll want to fill in this field. - example: WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0= + $ref: "#/components/schemas/ResolvedBidID" + description: + If the click is over an ad promotion, this is the `resolvedBidId` field received from + the `/auctions` request. In most situations, especially when reporting a sponsored + interaction, you'll want to fill in this field. entity: - $ref: '#/components/schemas/Entity' + $ref: "#/components/schemas/EventEntity" placement: - $ref: '#/components/schemas/Placement' + $ref: "#/components/schemas/Placement" occurredAt: - type: string - format: date-time - description: RFC3339 formatted timestamp including UTC offset. - example: '2009-01-01T12:59:59-05:00' + $ref: "#/components/schemas/occurredAt" opaqueUserId: - $ref: '#/components/schemas/OpaqueUserID' + $ref: "#/components/schemas/OpaqueUserID" id: - type: string - description: > - The marketplace's unique ID for the click. - This field ensures the event reporting is idempotent in case there is a network issue and the request is retried. - If there is no click model on the marketplace side, generate a unique string that does not change if the event is resent. - minLength: 1 - example: b39d39ed-ea0e-4059-9d15-4990b39c85a2 + $ref: "#/components/schemas/EventIdentifier" additionalAttribution: - $ref: '#/components/schemas/Entity' + $ref: "#/components/schemas/EventEntity" page: - $ref: '#/components/schemas/Page' + $ref: "#/components/schemas/Page" object: - $ref: '#/components/schemas/InteractionObject' + $ref: "#/components/schemas/InteractionObject" clickType: type: string - description: For sponsored events only, signals the specific interaction flavor with the listing. + description: + For sponsored events only, signals the specific interaction flavor with the listing. enum: - product - like @@ -2133,23 +2053,28 @@ components: externalCampaignId: type: string description: Marketplace provided ID for a campaign - example: 'awareness-campaign-2025' + examples: + - awareness-campaign-2025 externalVendorId: type: string description: Marketplace provided ID for a vendor - example: 'my-new-vendor' + examples: + - my-new-vendor deviceType: - $ref: '#/components/schemas/DeviceType' + $ref: "#/components/schemas/DeviceType" channel: type: string description: Optional. The channel where the event occurred. - enum: ['onsite', 'offsite', 'instore'] - example: 'onsite' - + enum: + - onsite + - offsite + - instore + examples: + - onsite Purchase: description: > - A purchase is sent to Topsort once a marketplace customer places an order. - These events are used to measure the effectiveness of an ad campaign. + A purchase is sent to Topsort once a marketplace customer places an order. These events are + used to measure the effectiveness of an ad campaign. type: object required: - occurredAt @@ -2159,33 +2084,32 @@ components: additionalProperties: false properties: occurredAt: - type: string - description: RFC3339 formatted timestamp, including UTC offset, of the instant in which the order was placed. Please note that purchases will NOT be attributed to an auction that happened after. - example: '2021-10-12T07:20:50.52Z' - format: date-time + $ref: "#/components/schemas/occurredAt" + description: + RFC3339 formatted timestamp, including UTC offset, of the instant in which the order was + placed. Please note that purchases will NOT be attributed to an auction that happened + after. opaqueUserId: - $ref: '#/components/schemas/OpaqueUserID' + $ref: "#/components/schemas/OpaqueUserID" items: type: array description: Items purchased. minItems: 1 items: - $ref: '#/components/schemas/PurchaseItem' + $ref: "#/components/schemas/PurchaseItem" id: - type: string - description: > - The marketplace unique ID for the order. - This field ensures the event reporting is idempotent in case there is a network issue and the request is retried. - If there is no unique ID for orders on the marketplace side, generate a unique string that does not change if the event needs to be resent. - minLength: 1 - example: 0e06c899-b2cd-4e0d-b0de-8aefb4b6d0a0 + $ref: "#/components/schemas/EventIdentifier" deviceType: - $ref: '#/components/schemas/DeviceType' + $ref: "#/components/schemas/DeviceType" channel: type: string description: Optional. The channel where the event occurred. - enum: ['onsite', 'offsite', 'instore'] - example: 'onsite' + enum: + - onsite + - offsite + - instore + examples: + - onsite PurchaseItem: type: object required: @@ -2197,33 +2121,46 @@ components: type: string description: The marketplace ID of the product being purchased. minLength: 1 - example: p_SA0238 + examples: + - p_SA0238 quantity: type: integer minimum: 1 default: 1 - description: Count of products purchased. - example: 2 + description: Amount of products purchased. + examples: + - 2 unitPrice: type: number format: double - minimum: 0.0 - exclusiveMinimum: true + exclusiveMinimum: 0 description: The price of a single item in the marketplace currency. - example: 12.95 + examples: + - 12.95 vendorId: type: string description: > - The vendor ID of the product being purchased. This field is optional - and should be filled in if 1. a product is sold by multiple vendors, or - 2. you want to use it for halo attribution + The vendor ID of the product being purchased. This field is optional and should be + filled in if 1. a product is sold by multiple vendors, or 2. you want to use it for halo + attribution minLength: 1 - example: v_8fj2D + examples: + - v_8fj2D + EventIdentifier: + type: string + description: > + A unique identifier for the request. This field ensures the event reporting is idempotent in + case there is a network issue and the request is retried. If there is no impression model on + the marketplace side, generate a unique string that does not change if the event is resent. + minLength: 1 + examples: + - eb874c98-bf4d-40a9-ae6d-fcf4cecb535c Pageview: type: object description: > - A page view represents the navigation of the user throughout the page. They are considered organic events. - In contrast to clicks or impressions, which are events within a page, a page view is the interaction with the full page, which can contain multiple objects. + A page view represents the navigation of the user throughout the page. They are considered + organic events. In contrast to clicks or impressions, which are events within a page, a page + view is the interaction with the full page, which can contain multiple objects. required: - occurredAt - opaqueUserId @@ -2232,31 +2169,34 @@ components: additionalProperties: false properties: page: - $ref: '#/components/schemas/Page' + $ref: "#/components/schemas/Page" occurredAt: - type: string - format: date-time - description: RFC3339 formatted timestamp including UTC offset. - example: '2009-01-01T12:59:59-05:00' + $ref: "#/components/schemas/occurredAt" opaqueUserId: - $ref: '#/components/schemas/OpaqueUserID' + $ref: "#/components/schemas/OpaqueUserID" id: type: string description: > - The marketplace's unique ID for the event. - This field ensures the event reporting is idempotent in case there is a network issue and the request is retried. - If there is no pageview model on the marketplace side, generate a unique string that does not change if the event is resent. + The marketplace's unique ID for the event. This field ensures the event reporting is + idempotent in case there is a network issue and the request is retried. If there is no + pageview model on the marketplace side, generate a unique string that does not change if + the event is resent. minLength: 1 - example: eb874c98-bf4d-40a9-ae6d-fcf4cecb535c + examples: + - eb874c98-bf4d-40a9-ae6d-fcf4cecb535c deviceType: - $ref: '#/components/schemas/DeviceType' + $ref: "#/components/schemas/DeviceType" channel: type: string description: Optional. The channel where the event occurred. - enum: ['onsite', 'offsite', 'instore'] - example: 'onsite' - + enum: + - onsite + - offsite + - instore + examples: + - onsite securitySchemes: - BearerAuth: - type: http + HTTPBearer: + description: A valid API key generated in Topsort's UI. scheme: bearer + type: http diff --git a/topsort-catalog-service.yml b/topsort-catalog-service.yml deleted file mode 100644 index d7d5620..0000000 --- a/topsort-catalog-service.yml +++ /dev/null @@ -1,488 +0,0 @@ -openapi: 3.0.1 -info: - title: Topsort Reference Catalog API - contact: - email: ralonso@topsort.com - license: - name: Apache 2.0 - url: http://www.apache.org/licenses/LICENSE-2.0.html - version: 1.0.0 - x-logo: - url: https://assets.topsort.com/Topsort_logo_icon_dark.svg - backgroundColor: '#fff' - altText: Topsort - description: Integration for Marketplaces' catalog queries - -servers: - - url: https://{marketplaceDomain} - variables: - marketplaceDomain: - default: demo.topsort.com/topsort/api - description: A URL that points to your catalog service - -tags: - - name: Catalog - description: Integration for Marketplaces' catalog queries. - - name: Models - x-displayName: All Models - description: | - ## Brand - - - ## Category - - - ## GetProductsByID Request - - - ## GetProductsByID Response - - - ## Paginated Brands Response - - - ## Paginated Categories Response - - - ## Paginated Products Response - - - ## Paginated Response - - - ## Paginated Vendors Response - - - ## Product - - - ## Vendor - - -security: - - BearerAuth: [] - -paths: - /: - get: - tags: - - Catalog - operationId: healthCheck - security: [] # No security - summary: Health Check - responses: - 200: - description: The service is up and ready to accept requests. - - /products: - post: - tags: - - Catalog - summary: Retrieves products by IDs - operationId: getProductsByID - requestBody: - description: An array of product IDs. - content: - application/json: - schema: - $ref: '#/components/schemas/GetProductsByIDRequest' - required: true - responses: - 200: - description: Returns the products' details, if available. - content: - application/json: - schema: - $ref: '#/components/schemas/GetProductsByIDResponse' - 401: - $ref: '#/components/responses/UnauthorizedError' - - /products/search: - get: - tags: - - Catalog - summary: Searches products - operationId: searchProducts - parameters: - - in: query - name: search - schema: - type: string - example: delirium tremens - description: > - The search string provided by the user. When a blank string is provided, - the string should match all products (e.g. all products with a given category ID). - required: true - - in: query - name: vendorID - schema: - type: string - minLength: 1 - example: '9SiwYqqL8vdG' - description: > - Vendor unique identifier. This identifier is given by the marketplace and allows this service - to match the vendor with the proper products. - required: false - - in: query - name: categoryID - schema: - type: string - minLength: 1 - example: ahEDqV5uhjj8 - description: Only retrieve products whose category matches the provided ID. - - $ref: '#/components/parameters/nextParam' - responses: - 200: - description: Returns products' details for the provided search terms if available, separated in pages. - content: - application/json: - schema: - $ref: '#/components/schemas/PaginatedProductsResponse' - 401: - $ref: '#/components/responses/UnauthorizedError' - - /categories: - get: - tags: - - Catalog - summary: Retrieves categories - operationId: getCategories - parameters: - - $ref: '#/components/parameters/nextParam' - responses: - 200: - description: Returns a complete list of categories, separated in pages. - content: - application/json: - schema: - $ref: '#/components/schemas/PaginatedCategoriesResponse' - 401: - $ref: '#/components/responses/UnauthorizedError' - - /vendors: - get: - tags: - - Catalog - summary: Retrieves vendors - operationId: getVendors - parameters: - - $ref: '#/components/parameters/nextParam' - responses: - 200: - description: Returns a complete list of vendors, separated in pages. - content: - application/json: - schema: - $ref: '#/components/schemas/PaginatedVendorsResponse' - 401: - $ref: '#/components/responses/UnauthorizedError' - - /brands: - get: - tags: - - Catalog - summary: Retrieves brands - description: > - This endpoint is optional. It is used to allow advanced use cases for Banner Ads. Talk to - your Account Manager to understand whether you need to implement this endpoint. - operationId: getBrands - parameters: - - in: query - name: search - schema: - type: string - example: delirium tremens - description: > - The search string provided by the user. In case this parameter is missing or an empty - string is provided, all brands should be returned taking into account the other - parameters. - required: false - - in: query - name: vendorID - schema: - type: string - minLength: 1 - example: '9SiwYqqL8vdG' - description: > - Vendor unique identifier. This identifier is given by the marketplace and allows this - service to match the vendor with the proper brands. - required: false - - $ref: '#/components/parameters/nextParam' - responses: - 200: - description: Returns a complete list of brands, separated in pages. - content: - application/json: - schema: - $ref: '#/components/schemas/PaginatedBrandsResponse' - 401: - $ref: '#/components/responses/UnauthorizedError' - -components: - responses: - UnauthorizedError: - description: Credentials are missing or invalid. - - schemas: - GetProductsByIDRequest: - type: array - items: - type: string - minLength: 1 - minItems: 0 - maxItems: 50 - example: - - eyGqR4YQgBJa - - KHqzavLNS25n - - wJLZ4TCNZtEW - - GetProductsByIDResponse: - type: array - items: - $ref: '#/components/schemas/Product' - minItems: 0 - maxItems: 50 - - PaginatedResponse: - type: object - properties: - next: - description: > - Id of the next page. This could be for example a page number (as a string) or a cursor - identifying the next page. This attribute will be passed in the `next` query parameter. - type: string - minLength: 1 - example: asTpl1k746 - - Product: - type: object - description: A Product represents a product listed in a marketplace. - properties: - id: - description: The product ID. - type: string - minLength: 1 - example: eyGqR4YQgBJa - readOnly: true - name: - description: The product name. - type: string - minLength: 1 - example: Delirium Tremens Beer Bottle 330cc x6 - description: - description: The product description. - type: string - minLength: 1 - example: Named as \"Best Beer in the World\" in 2008 at the World Beer Championships in Chicago, Illinois. - vendorID: - description: The vendor ID. - type: string - minLength: 1 - example: 9SiwYqqL8vdG - vendorName: - description: The vendor name. - type: string - minLength: 1 - example: Huyghe Brewery - stock: - description: How many items of this product you have available. If this number is greater than 0, it means you have it in stock and you can fulfill a purchase. - type: integer - format: int32 - minimum: 0 - example: 126 - price: - description: The product price in the minimum currency unit (e.g. cents if applicable). Refer to [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) to check how many decimals are used in your currency. - type: integer - format: int32 - minimum: 1 - example: 14900 - imageURL: - description: The product image URL. Its size should be between 250x250 and 600x600 pixels. - type: string - format: uri - example: https://r.btcdn.co/r/eyJzaG9wX2lkIjozMzU4LCJnIjoiMjYweCJ9/1759e16e6314a24/669830-Cerveza_Delirium_Tremens_Botella_330cc_x6.png - categoryID: - description: The category id. - type: string - minLength: 1 - example: ahEDqV5uhjj8 - categoryName: - description: The category name. - type: string - minLength: 1 - example: Beers/Belgian - required: - - id - - name - - ProductsResponse: - type: object - required: - - response - properties: - response: - type: array - items: - $ref: '#/components/schemas/Product' - minItems: 0 - maxItems: 50 - - PaginatedProductsResponse: - allOf: - - $ref: '#/components/schemas/PaginatedResponse' - - $ref: '#/components/schemas/ProductsResponse' - - Category: - type: object - properties: - id: - description: > - The category ID. If there is no ID for categories in the marketplace, this - can be the category name as long as it is unique. - type: string - minLength: 1 - example: ahEDqV5uhjj8 - name: - description: The category name. - type: string - minLength: 1 - example: Beers/Belgian - required: - - id - - name - - CategoriesResponse: - type: object - required: - - response - properties: - response: - type: array - items: - $ref: '#/components/schemas/Category' - minItems: 0 - maxItems: 50 - example: - - id: ahEDqV5uhjj8 - name: Beers/Belgian - - id: cJfoUUzG6GOy - name: Beers/Ales/Amber - - id: oTcnv0fJCRiL - name: Beers/Lagers/Bocks - - id: JspphvZBzV09 - name: Beers/Lagers/Blonde - - PaginatedCategoriesResponse: - allOf: - - $ref: '#/components/schemas/PaginatedResponse' - - $ref: '#/components/schemas/CategoriesResponse' - - Vendor: - type: object - properties: - id: - description: The vendor ID. - type: string - minLength: 1 - example: 9SiwYqqL8vdG - name: - description: The vendor name. - type: string - minLength: 1 - example: Huyghe Brewery - required: - - id - - name - - VendorsResponse: - type: object - required: - - response - properties: - response: - type: array - items: - $ref: '#/components/schemas/Vendor' - minItems: 0 - maxItems: 50 - example: - - id: C0n7J6j0WySR - name: Black Neck Brewery - - id: y7v6kSGGUUFn - name: Brewery Chile SA - - id: vhvg6ioBj5fk - name: Coda Brewery - - id: IMwMGVfSsEpQ - name: Kunstmann Brewery - - id: zo8UXchnFWZu - name: United Brewery - - id: 9SiwYqqL8vdG - name: Huyghe Brewery - - PaginatedVendorsResponse: - allOf: - - $ref: '#/components/schemas/PaginatedResponse' - - $ref: '#/components/schemas/VendorsResponse' - - Brand: - type: object - properties: - id: - description: The brand ID. - type: string - minLength: 1 - example: 9SiwYqqL8vdG - name: - description: The brand name. - type: string - minLength: 1 - example: Pepsi - imageURL: - description: The brand image URL. Its size should be between 250x250 and 600x600 pixels. - type: string - format: uri - required: - - id - - name - - BrandsResponse: - type: object - required: - - response - properties: - response: - type: array - items: - $ref: '#/components/schemas/Brand' - minItems: 0 - maxItems: 50 - example: - - id: bC0n7J6j0WySR - name: Black Neck Brewery - imageURL: https://cdn.marketplace.com/bnb.png - - id: by7v6kSGGUUFn - name: Brewery Chile - imageURL: https://cdn.marketplace.com/bc.png - - PaginatedBrandsResponse: - allOf: - - $ref: '#/components/schemas/PaginatedResponse' - - $ref: '#/components/schemas/BrandsResponse' - - securitySchemes: - BearerAuth: - type: http - scheme: bearer - - parameters: - nextParam: - in: query - name: next - schema: - type: string - minLength: 1 - description: > - The string identifying the requested page. In case this parameter is missing then the first - page should be returned. Note that the specifics about this parameter controlled entirely by - what's returned as `next` in a paginated response and could either be a page number or a - cursor.