---
openapi: 3.0.3
info:
  version: 0.0.1
  x-audience: public
  title: Catalog Popularity
  description: Catalog Popularity allows to write Usage & Popularity statistics to
    DIC and read Usage & Popularity statistics from DIC.
servers:
- url: /rest/dataUsage/v1
tags:
- name: Popularity
  description: Endpoints for reading popularity/usage data
- name: Aggregated Data
  description: Endpoints to submit your own usage data and track its writing
security:
- basicAuth: []
- jwtAuth: []
paths:
  /aggregatedData/submit:
    post:
      tags:
      - Aggregated Data
      summary: Submit aggregated data
      operationId: submitAggregatedData
      description: "Uploads aggregated data required to calculate Popularity Score\
        \ for assets. \n\nThere are 2 different ways to provide keys and type (see\
        \ examples).\n"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              maxItems: 1000
              items:
                $ref: "#/components/schemas/AggregatedData"
            examples:
              Hierarchical:
                value:
                - assetLocator:
                    type: RDBMS
                    product: postgres
                    keys:
                    - system_name
                    - database_name
                    - schema_name
                    - table_name
                    - column_name
                  toDate: 2025-01-30T00:00:00Z
                  timePeriod: 30_DAYS
                  queryCount: 1203
                  distinctUsers: 14
              AssetId:
                value:
                - assetLocator:
                    type: assetId
                    product: postgres
                    keys:
                    - 0194da16-5210-7565-ab4b-885ea3322622
                  toDate: 2025-01-30T00:00:00Z
                  timePeriod: 30_DAYS
                  queryCount: 1203
                  distinctUsers: 14
      responses:
        "202":
          description: Submits a batch of data to be written (asynchronous endpoint).
          headers:
            Location:
              schema:
                type: string
              description: Endpoint to retrieve batch status.
              example: /aggregatedData/jobs/b00db37d-282e-4ea9-86d4-5881660ba46a
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Job"
        "400":
          $ref: "#/components/responses/InvalidRequest400"
        "401":
          $ref: "#/components/responses/InvalidRequest401"
        "403":
          $ref: "#/components/responses/InvalidRequest403"
        "404":
          $ref: "#/components/responses/InvalidRequest404"
  /aggregatedData/jobs:
    get:
      tags:
      - Aggregated Data
      parameters:
      - $ref: "#/components/parameters/Status"
      - $ref: "#/components/parameters/Offset"
      - $ref: "#/components/parameters/Limit"
      summary: Find jobs
      operationId: findJobs
      description: |
        Returns a list of jobs related to the data aggregation process.
      responses:
        "200":
          description: List of jobs successfully retrieved. The report of the job
            will not be present.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JobsResultPage"
        "400":
          $ref: "#/components/responses/InvalidRequest400"
        "401":
          $ref: "#/components/responses/InvalidRequest401"
        "403":
          $ref: "#/components/responses/InvalidRequest403"
        "404":
          $ref: "#/components/responses/InvalidRequest404"
  /aggregatedData/jobs/{id}:
    get:
      tags:
      - Aggregated Data
      summary: Find job by id
      operationId: findJobById
      description: |
        Returns a job related to the data aggregation process by its ID.
      parameters:
      - name: id
        in: path
        required: true
        description: The job ID to retrieve.
        example: b00db37d-282e-4ea9-86d4-5881660ba46a
        schema:
          type: string
          format: uuid
      responses:
        "200":
          description: Job successfully retrieved.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Job"
        "400":
          $ref: "#/components/responses/InvalidRequest400"
        "401":
          $ref: "#/components/responses/InvalidRequest401"
        "403":
          $ref: "#/components/responses/InvalidRequest403"
        "404":
          $ref: "#/components/responses/InvalidRequest404"
  /findPopularity:
    post:
      tags:
      - Popularity
      summary: Find Popularity
      operationId: findPopularity
      description: Returns latest information about the popularity and usage for assets
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              maxItems: 100
              items:
                $ref: "#/components/schemas/AssetLocator"
            examples:
              Hierarchical:
                value:
                - type: RDBMS
                  product: postgres
                  keys:
                  - system_name
                  - database_name
                  - schema_name
                  - table_name
                  - column_name
              AssetId:
                value:
                - type: assetId
                  product: postgres
                  keys:
                  - 0194da16-5210-7565-ab4b-885ea3322622
      responses:
        "200":
          description: List of popularity scores
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/findPopularityResponse"
        "400":
          $ref: "#/components/responses/InvalidRequest400"
        "401":
          $ref: "#/components/responses/InvalidRequest401"
        "403":
          $ref: "#/components/responses/InvalidRequest403"
        "404":
          $ref: "#/components/responses/InvalidRequest404"
components:
  parameters:
    Offset:
      name: offset
      in: query
      description: |
        The index of the first result to retrieve.

        If not set (offset = <code>0</code>), results will be retrieved starting from row <code>0</code>.
      schema:
        type: integer
        format: int32
        default: 0
        minimum: 0
        maximum: 2147483647
    Limit:
      name: limit
      in: query
      description: |
        The maximum number of results to retrieve.

        If not set, the default limit  (limit = <code>0</code>) will be used. The maximum value for this parameter is
        <code>500</code>.
      schema:
        type: integer
        format: int32
        default: 10
        minimum: 1
        maximum: 500
    Status:
      name: status
      required: false
      in: query
      description: |
        The status of the jobs to retrieve.

        If not set, this filter will not be applied and everything will be returned.
      schema:
        type: string
        enum:
        - Waiting
        - Running
        - Completed
        - Failed
  schemas:
    StandardErrorResponse:
      type: object
      properties:
        statusCode:
          type: integer
          description: HTTP response code
        titleMessage:
          type: string
        helpMessage:
          type: string
        userMessage:
          type: string
        errorCode:
          type: string
    AssetLocator:
      description: |
        Describes where to search for a specific Catalog asset. It might match more than one result.

        It also specifies the type of the datastore of origin and its commercial name
      type: object
      required:
      - type
      - keys
      properties:
        type:
          $ref: "#/components/schemas/Type"
        product:
          $ref: "#/components/schemas/ProductName"
        keys:
          $ref: "#/components/schemas/Keys"
    Type:
      description: |
        Identifier for the datastore type of origin.
      type: string
      example: RDBMS
    ProductName:
      description: |
        Commercial name of the datastore of origin.
      type: string
    Keys:
      description: |
        Ordered list of names for each member of the hierarchy of an item.
      type: array
      minItems: 1
      items:
        type: string
        nullable: false
    AggregatedData:
      type: object
      properties:
        assetLocator:
          $ref: "#/components/schemas/AssetLocator"
        toDate:
          type: string
          format: date-time
          description: End date of the 30-day window used for popularity calculation
          example: 2025-01-30T00:00:00Z
        timePeriod:
          type: string
          example: 30_DAYS
        queryCount:
          type: integer
          example: 1203
        distinctUsers:
          type: integer
          description: Number of distinct users that have queried the asset
          example: 14
    JobsResultPage:
      type: object
      required:
      - results
      properties:
        results:
          type: array
          items:
            $ref: "#/components/schemas/Job"
    Job:
      type: object
      required:
      - id
      - createdBy
      - createdOn
      - startDate
      - status
      properties:
        id:
          type: string
          format: uuid
        createdBy:
          type: string
          format: uuid
        createdOn:
          type: string
          format: date-time
        startDate:
          type: string
          format: date-time
        endDate:
          type: string
          format: date-time
        status:
          type: string
          enum:
          - Waiting
          - Running
          - Completed
          - Failed
        report:
          type: object
          additionalProperties: true
    Popularity:
      type: object
      properties:
        score:
          type: string
          example: 4 - Very high
        calculatedAt:
          type: string
          format: date-time
          example: 2020-01-01T00:00:00Z
    UsageData:
      type: object
      properties:
        fromDate:
          type: string
          format: date-time
          example: 2020-01-01T00:00:00Z
        toDate:
          type: string
          format: date-time
          example: 2020-12-01T00:00:00Z
        queryCount:
          type: integer
          example: 1200
        distinctUsers:
          type: integer
          example: 14
    findPopularityResponse:
      type: object
      required:
      - assetLocator
      properties:
        assetLocator:
          type: array
          items:
            $ref: "#/components/schemas/AssetLocator"
        popularity:
          $ref: "#/components/schemas/Popularity"
        usageData:
          $ref: "#/components/schemas/UsageData"
        errorMessage:
          type: string
  responses:
    InvalidRequest400:
      description: The request is not valid.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/StandardErrorResponse"
          example:
            statusCode: 400
            titleMessage: Invalid Request
            helpMessage: Please check the application logs for more information.
            userMessage: The request is not valid.
            errorCode: invalidRequest
    InvalidRequest401:
      description: The client is not authenticated.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/StandardErrorResponse"
          example:
            statusCode: 401
            titleMessage: Unauthorized
            helpMessage: Please check the application logs for more information.
            userMessage: Failed to authenticate request through basic credentials
            errorCode: authenticationFailed
    InvalidRequest403:
      description: The user lacks permissions.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/StandardErrorResponse"
          example:
            statusCode: 403
            titleMessage: Forbidden
            helpMessage: Please check the application logs for more information.
            userMessage: The user does not have the required permissions.
            errorCode: authorizationFailed
    InvalidRequest404:
      description: Resource not found.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/StandardErrorResponse"
          example:
            statusCode: 404
            titleMessage: Not Found
            helpMessage: Please check the application logs for more information.
            userMessage: The resource could not be found
            errorCode: Not found
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: Collibra REST API authentication using Basic Authentication.
    jwtAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Collibra REST API authentication using JSON Web Token.
