catalog-crud-api.yml

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
      <SchemaDefinition schemaRef="#/components/schemas/Category" />

      ## Product
      <SchemaDefinition schemaRef="#/components/schemas/Product" />

      ## Vendor
      <SchemaDefinition schemaRef="#/components/schemas/Vendor" />