topsort-catalog-service.yml

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

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

      ## GetProductsByID Request
      <SchemaDefinition schemaRef="#/components/schemas/GetProductsByIDRequest" />

      ## GetProductsByID Response
      <SchemaDefinition schemaRef="#/components/schemas/GetProductsByIDResponse" />

      ## Paginated Brands Response
      <SchemaDefinition schemaRef="#/components/schemas/PaginatedBrandsResponse" />

      ## Paginated Categories Response
      <SchemaDefinition schemaRef="#/components/schemas/PaginatedCategoriesResponse" />

      ## Paginated Products Response
      <SchemaDefinition schemaRef="#/components/schemas/PaginatedProductsResponse" />

      ## Paginated Response
      <SchemaDefinition schemaRef="#/components/schemas/PaginatedResponse" />

      ## Paginated Vendors Response
      <SchemaDefinition schemaRef="#/components/schemas/PaginatedVendorsResponse" />

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

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